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

  • The new English version of the SilverStripe book is out. This is great news. A first book for any open source project is a real milestone, not many projects get that far. I encourage the authors to publish it on the Internet, not for my sake, but for the community. We all know as developers the frustrations of poor documentation. Every time a developer hits a road block with their code, they turn to documentation; failing that they turn to a community for help. If after several failures they cannot get something working, it’s likely they’ll give up and try something else.

    Posted by Droid sales, 5 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.