SilverStripe

Updates to our documentation

Posted by Joanna McLeod on 18 January 2011

Back in June last year, we asked for help in updating the SilverStripe documentation. We're happy to announce now that those updates have been made.

Specifically:

• First, we started a documentation team and a public mailing list that reviews existing material and keeps editorial oversight on new content. This raises the bar for our documentation quality, and we're still looking for community members to have a significant stake in this team.
• Second, we've moved the majority of the documentation to being stored as text files in the same version control repository as the SilverStripe CMS software itself. There needs to be separate sets of documentation for upcoming releases of SilverStripe distinct from the current version, and this approach ties the code and documentation together elegantly. This means we converted a great amount of text from the current DokuWiki format into our syntax of choice, Markdown. You can read the documentation by downloading it, or by visiting doc.silverstripe.com, which is automatically updated whenever the underlying documentation is changed in version control.
• Third, the doc.silverstripe.org website has been visually redesigned, and is entirely based of content sourced from code files as described above. The scope for content at this website remains the same, and covers installation, developer tutorials, and concepts like forms and themes. It links to detailed documentation for classes and objects at api.silverstripe.com.
• Fourth, alongside the move of documentation parts to version control, a clear separation of "official" documentation from user contributed content should help to keep information relevant and manageable. 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.

Overall, you shouldn't find that content has changed drastically, just that it's presented better, and isn’t as easily editable as when we were using a wiki. This new format means that we can keep all content up to date better.

We realise that removing wiki edit rights means that the barriers to contributing are a little higher, so we're imagining we’ll have fewer but more dedicated contributors. We really want to emphasise that we don't want to stop anyone from contributing. The site is open source, all the content is open source, and licensed under Creative Commons. It's as open as we can make it while still maintaining a manageable source that's current. For more information on how you can contribute, please read our contribution guide.

Here are some ideas on how you can help:

• Review existing documentation and point us to technical errors and typos (through the comments)
• Write a new how-to or recipe (e.g. “How to expose my DataObjects as an RSS feed”)
• Improve the sapphiredocs module (see open tickets)
• Help us moderate comments
• Become part of the documentation team to help review and restructure content

Last but not least, we want to thank all the dedicated individuals that helped getting this baby live, by writing migration scripts, fixing up formatting, reviewing content, coding, and much more!