Calling for help in documentation

Posted by Ingo Schommer on 2 June 2010

The criticism we hear most often from the developer community is that, with the exception of our books, SilverStripe needs to improve its developer documentation. And it's a fair point.  

We made some decisions regarding our documentation a while back that we thought would work at the time - a best guess as to how to proceed. But these turned out to limit us in ways we simply didn't foresee.

First, the wiki format used on doc.silverstripe.org since we've opensourced in 2007 didn't scale well. Now, we chose a wiki because this way we could have everyone contribute without putting any barriers in the way. The problem was that it wasn't used that much. Sure, anyone could press the "edit" button, but in practice, few developers did - and information quickly became outdated. 

Complicating that was that there were months-long gaps between when we implemented new features into the test builds and when we finally released them. Because the Wiki was always "live," we couldn't change the documentation for features we didn't know would make it into release until close to, or after, the release. So you're likely to forget the code later on, or not be able to do it at the same level of detail as you would have been able to when the code was fresh. 

Then, our API documentation at api.silverstripe.org was poorly presented, not targeted at actual releases, and often severely outdated. In order to enable developers to effectively look up information like method parameters or class usage, we need to do a lot better than this. As a starting point, we've completely rewritten and "decluttered" the phpDocumentor-based templates (see announcement and discussion).

Now, we do not have a master plan on how to improve the situation, but here are some some high-level ideas that we want to put out for community feedback.

First, we could start a documentation team that can review existing material and keep editorial oversight on new content. This will be an important milestone in raising the bar for our documentation quality, and we're looking for community members to have a significant stake in this.

Second, we'd like to move some of the documentation closer to the code, and into version control. There needs to be a separate set of documentation for upcoming releases of SilverStripe than there is for the current version, at the time when features are implemented, not six months afterwards. This means converting a great amount of text from the current DokuWiki format into our syntax of choice, Markdown.

Third, the doc.silverstripe.org wiki should become more of a "conceptual glue" for highlevel concepts like "forms" or "themes", and point people towards the detailed documentation inside the API. 

Fourth, alongside the move of documentation parts to version control, a clear separation of "official" documentation from user contributed recipes should help to keep information relevant and manageable. To be clear: This doesn't change the fact that anybody can contribute to "official" docs, but hopefully we can establish a more proactive editorial process through a documentation team to ensure new content lands in the right place.

Fifth, we're considering a unified search interface across both doc.silverstripe.org and api.silverstripe.org can help to avoid duplicated and hidden information. This will be based on the OpenSearch specification, which will allow you to integrate a search right in your browser search bar for quick access.

Sixth, and finally, we want to document our way of writing documentation (meta documentation, anyone?!) - guidelines what needs to go where, in which style and format.

Now, documentation is a time and labour intensive process, and to be honest, we're quite a small core team thats already swamped with other responsibilities. We've had a massive push in getting the first and second SilverStripe book out, but also need to stay committed to having up-to-date and freely available documentation on top of that.

We hope to get a discussion going to find out where we need to focus and if we can make it a priority in the overall community to improve SilverStripe documentation. And to do that, we're hoping you can provide suggestions in the comments section of this post.

What annoys you the most about SilverStripe documentation? Where do you go to get information about developing in SilverStripe? And would you be willing to contribute to documentation efforts?

Post your comment

Note: Comments are moderated and won't show until they are approved

Comments

  • @tim: I think a "generalized procedure" is practically impossible - nobody is stopping you from researching the topic in question is actually not documented, and filing a documentation-related ticket on open.silverstripe.org linking back to the forum thread.

    On the other hand, somebody still needs to clean up and formalize this preliminary documentation post, and thats where the effort lies - I think very few posts would be written in "howto-style" to be copied straight into documentation.

    Could you give us an example of where you see a forum post answer being transferrable into docs in a generalized way?

    Posted by Ingo, 4 years ago

  • If somebody were to develop a generalized procedure for taking an answer from the forum into a wikipage that would be amazing. I'm not sure how it would work, but if there were a way that when I get a satisfactory answer to a question it would be easy for me to make a new documentation page to go with that, or add to current docs. The biggest problem is that the only way to find out functionality is to Google search and find forum posts.

    also, I think wordpress.org is a fantastic model to emulate.

    Posted by tim, 4 years ago

  • i really love the idea of what kickstarter.com does. opensource is fantastic, but many times i find myself struggling with a certain development issue, post it on a bugtracker, and see there's already some others in despair - often i wouldn't hesitate to get my credit card for some relief, and i'm sure others would follow.

    as for the documentation, why not have a kickstarter projekt for it? of course it would need to be clearly identified which tasks could be accomplished in such a project, but maybe it's an option for some specific documentation issue?

    Posted by max, 4 years ago

  • Howdy all, we had a great discussion on this topic back in October in the silverstripe-dev group. Still lots of ideas and feedback there also:

    http://groups.google.com/group/silverstripe-dev/browse_thread/thread/b9ee6dce8b7b5f1/

    Posted by Dalesaurus, 4 years ago

  • Hello Billy, great to hear that you're willing to contribute funding to this effort! We're in the tricky situation of being a commercial company with an opensource product, but no separate charity (yet). Hence it will be too ambiguous for us to take on funding for generic opensource work (we're always open to funded development of specific features and consulting of course). If you're willing to collect funds for this cause, I'd recommend this to be coordinated from within the community, e.g. through http://www.kickstarter.com/. For now, we're just looking for help in technical and content-related tasks :)

    Posted by Ingo, 4 years ago

  • As mentioned in the main post, most developers are very busy. It's hard to dedicate a lot of time to documentation. What if we had a way to at least donate funds to the main documentation/editorial team? The few people coordinating the entire effort. That might allow them to dedicate a bit more time to organizing this, speeding up the process.

    Posted by Billy, 4 years ago

  • Alright, I've created a Google group for this: http://groups.google.com/group/silverstripe-documentation - please join if you're keen to help out, but also if you're just interested in further progress :) I'd recommend to continue any further discussion there instead of on the (rather limited) blog comments.

    Posted by Ingo, 4 years ago

  • Hey everybody, I'm offline for the long weekend here in New Zealand. Next week I'm planning to set up either a new forum on ss.org or a Google mailinglist for "silverstripe-documentation" so we can continue the discussion there.

    Action points for the next couple of weeks:
    * Search for api.silverstripe.org (Ingo)
    * Discuss documentation repository (dedicated git? /doc subfolder within module?)
    * Review existing rewritten documentation (we've started this internally about a year ago that never got published due to various reasons)
    * Set up draft structure for how-tos and guides (we've already done some work there)
    * Review user comments on disqus, fix smaller things straight on the wiki, and file larger issues as tickets on open.silverstripe.org
    * Evaluate diem documentation project vs. Will's sapphiredocs
    * Convert existing documentation to Markdown (via pandoc?), and possibly do some regex postprocessing
    * Review Markdown documentation (fix image paths, make internal links relative, etc.)

    Sounds like a plan? I'm thrilled to see there's so much interest to help! If you want to start with something straightforward (e.g. doc.ss.org -> Markdown conversion, review user comments) over the weekend, don't let the planning hold you back though ;)

    Posted by Ingo, 4 years ago

  • I am interested in helping make the documentation better. Let me know how I can get started, or if you want me to help with the planning phase.

    Posted by Dan, 4 years ago

  • Hi Ingo,

    Has SS considered also doing "How-to" instructional video such as with TekPub.com?

    I'd pay a small premium for concise up to date content so SilverStripe.com could also make a little to recoup costs.

    You could also then link to written docs for further info and encourage contribution. Where "how-to" content might also help to identify where this effort is required.

    SS could even approach Rob at Tekpub it might be a way to broaden SilverStripe's audience. Otherwise creating a site to host content is "How-to" showcase in its self.

    Whatever the case I like what you guys are doing and given a bit more knowledge and opportunity I'd be happy to help out.

    Posted by Matt, 4 years ago

RSS feed for comments on this page | RSS feed for all comments

Want to know more about the company that brought you SilverStripe? Then check out SilverStripe.com

Comments on this website? Please give feedback.