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?
