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

  • I've been working in software development for over a decade and just wanted to say that when I first was introduced to SilverStripe I was impressed. It is clean and I noticed no bugs. Great work.

    Posted by Jack John, 2 years ago

  • I'm a huge fan of SilverStripe. Keep the blog posts coming. I check here almost daily.

    Posted by FryGuy, 2 years ago

  • Will your documentation be available in .pdf format?

    Posted by Kenny, 2 years ago

  • I think that the best option may be the unified search interface across both doc.silverstripe.org and api.silverstripe.org. This idea will make finding helpful information easier and will reduce the time needed to find the information we may be looking for since we will be able to avoid reading through duplicate information. I think all the efforts you all are putting into the documentation is a great step forward. Being able to properly use SliverStripe will help people get the most out if it. I'm glad you are putting so much time and effort into creating such a great CMS title. Many people don't realize just how widespread the use of CMS software really is. Sure, people use it to create websites, but many people don't realize that it is also widely used in the medical field. Aside from medical journals, CMS software is a top platform for which many medical professionals share important information. I'm happy to know that SilverStripe has a promising future and I cannot wait to see how great it will become!

    Posted by cincinnati urologist, 3 years ago

  • I find myself coming to your blog more and more often to the point where my visits are almost daily now!

    Posted by Keep Man Interested, 3 years ago @KeepManInterested

  • I just sent this post to a bunch of my friends as I agree with most of what you’re saying here and the way you’ve presented it is awesome.

    Posted by How To Get ABS, 3 years ago @HowToGetABS

  • Great read... Thank you for sharing this informative article...

    Posted by Contus Support, 4 years ago

  • oh, I see - it was confusing because there is the spot to log into Disqus, I wasn't looking for a second place to log in.

    Posted by tim, 4 years ago

  • Tim, thanks for the example. Something I'd like to know is what is preventing you from editing http://doc.silverstripe.org/datepickerfield page?
    It is a wiki with public access. Potentially it is usability issue that makes it difficult to know that you can, and where you can, register?

    Posted by Sigurd Magnusson, 4 years ago

  • @Ingo

    Example:

    http://silverstripe.org/general-questions/show/283185?start=8#post286359

    never would have found that on my own, nor is it documented in any meaningful way. if I could modify the wiki I'd be happy to add a note, but I can't. comment threads on documentation pages are not a good solution.

    Posted by tim, 4 years ago

1 2 3 4 next »

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.