What's up docs? An investigation into SilverStripe documentation

Posted by Cam Findlay on 25 June 2014

Let's face it, a common gripe in open-source is documentation. SilverStripe is no exception here, though we would like to do something about it. While we have had some semblance of developer documentation up at http://docs.silverstripe.org for some time, it often takes a back seat in favour of more technical and code related contributions from the community. In fact, we have raised the issue in the past and made some significant improvements, however it's time for more. The key thing to remember here is that that documentation has been and will continue to be a collaborative effort built up by contributions from the community (so a big thanks to all those that have contributed thus far!).

Part of my role as Community Awesomeness Manager here at SilverStripe, is to work within the community to both ensure knowledge flows and that you have the tools you need to build awesome projects using the SilverStripe Framework and CMS. Documentation is something we not only need to correct in the short term, but to ensure as we move forward that documentation has a good process to ensure continued contribution to it by the community in a structured and meaningful way.

Since I engage with community members in many spaces, I get many perspectives and opinions. Common is the "docs sux!" message. However, without any context this is more an outlet of frustration for that user, rather than constructive feedback I can drive action from and work inside SilverStripe to get some traction on fixing things. So I am starting a conversation and aiming to facilitate some discussion leading towards developing a clear idea of what we should do next to start improving SilverStripe's open-source documentation.

So far I have guided great feedback from our IRC channel and our core developer list (a Google group that talks more about the high level work going on around our CMS and Framework). Now I would like to widen the conversation out to the whole community. Whether you are a newcomer to SilverStripe or have been using it for a while and still use the documentation as a reference it would be great to get your opinions of where the key issues lay and how you think we might improve.

My role in this is to gather all the information and build out a plan to get documentation into shape and create a robust process to ensure SilverStripe documentation becomes a high quality and useful learning and knowledge resource well into the future. I'd like to do so in the spirit of open-source, that is, transparent, open to input from the community and sharing knowledge as we create something valuable.

Let's reimagine what SilverStripe documentation can be and contribute to make it useful for SilverStripers now and in the future. Either leave me a comment here, email me at community@silverstripe.org or contribute to the ongoing conversation over on the core developer list.

Looking forward to your feedback. 

 

Post your comment

Note: Comments are moderated and won't show until they are approved

Comments

  • What I would really appreciate is a 'beyond-the-basics' manual on how to create a website, that has a little more complexity. E.g. multi-column landing-page, how to incorporate a rotating banner image, etc. And all of these documented from start to end based on the best practices from the developer/core team themselves.

    Posted by Emil Cristen, 2 months ago @emilcristen

  • Thanks for you points James, seems along the lines of what others are thinking too.

    Posted by Cam Findlay, 2 months ago @cameronfindlay

  • A few points that I'd like to see improved are:

    Framework Documentation
    --
    SilverStripe desperately needs a guide on how to build a basic web app using just the SilverStripe Framework module. Dealing with things like routes, pages, logins etc. About a year ago I tried to create a web app, using just he SilverStripe Framework but really struggled to find information on how to get the basics working.

    Documentation Search
    --
    I rarely find the SilverStripe documentation search function returns useful results. E.g. if I type 'get' into the docs search looking for how to get, filter and sort objects, the Datamodel page that explains this isn't even in the first page of results. If I Google 'SilverStripe get', it's the first result. And the global SilverStripe search at http://www.silverstripe.org/search doesn't provide a way to just show results at docs.silverstripe.org, it lumps in api results too, and normally I am looking for something specifically in docs or api, not both!

    Real World Examples
    --
    It would also be great to have more real world code examples for common things. Like the Partial Caching documentation doesn't even have an example on how to cache a basic navigation menu (while keeping LinkingMode working), there is also no indication on best practice for caching. E.g. on a basic brochure site, should I always cache the nav, anything else that should always be cached? I understand that every site is different, but there are common basic elements that a lot of sites use like navigation, latest blog posts, testimonials, and some indication on the best practice for dealing with their caching would be very useful. Perhaps adding a caching chapter to the tutorial would be useful?

    Configuration
    --
    Another page that comes to mind is the Configuration page, when I first went looking for how to store a simple value in a config variable and access it from a controller, the current Configuration page doesn't really explain how to do this in a straightforward manner, and goes into a lot of detail, but doesn't cover the basics sufficiently.

    I look getting the docs improved, and shall help wherever I can.

    Posted by James Cocker, 2 months ago @itisjames

  • Hi all, please feel free to leave your comment here regarding SilverStripe documentation. I will be collating everything up and proposing some changes in the near future. Thanks!

    Posted by Cam Findlay, 2 months ago @cameronfindlay

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.