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 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 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 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 and 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


  • This has been one of my gripes with Silverstripe from the beginning - it's awesome, insanely flexible and you can bend it to do pretty much whatever you need, but sometimes the lack of documentation means that figuring out how to bend it can sometimes take days instead of hours.

    Recently I made a post on the forums about using sessions, and Willr promptly documented it in the wiki, with examples. This was EXCELLENT and invaluably useful.

    I definitely think that having a team responsible around the documentation is necessary. I also think that the documentation could be improved quite quickly if when, whenever a doc team member saw a forum question that wasn't documented, they were able to create one - with working examples. This would stop the same question from being asked over and over.

    I think that initially, monitoring the forums is a pretty good way to make the existing documentation miles better, as this is where we developers turn to when we can't figure something out.

    Posted by Pingu, 4 years ago

  • Hit the nail on the head!

    Separate documentation for each release version would be grand, but don't do it the PHP way - make it clear what version the docs belong to, and allow a user to traverse back.

    I love the 'recipes' concept, but it's no use if the content is outdated. However, other systems deal with this using 'Related content' type areas - if these are autogenerated, it's likely that the name will be used in the related content too.

    The key aspect for me is something inbetween the API docs and the current wiki docs. It's that 'glue' layer really - especially annoying when you need to figure out how to circumvent something (such as augmentSql used in multisites).

    And I'd be willing to contribute where possible, but as with most (assumed), time is scarce :)

    Posted by Keith Humm, 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

Comments on this website? Please give feedback.