Content is King: Documentation for SilverStripe

Posted by Philipp Krenn on 16 January 2012

Guest blogger Philipp Krenn is one of SilverStripe's Google Summer of Code students from 2007. More recently, he has written the latest book on SilverStripe. For the upcoming 3.0 release, he will contribute to the official documentation — an area which can always do with some additional love. You can stay in touch by following @xeraa on Twitter.

I hope you all had some time off and enjoyed the holidays. I surely did - it was skiing time in the northern hemisphere as you can see from my photo. Now that the holidays are over, it is time time to get back to business. With all the heavy work on SilverStripe 3.0, an important part will be the documentation. Stating the obvious, I will try to elaborate a little further.

Back in the Day

I started playing around with SilverStripe in spring 2007 pretty soon after its initial release - version 2.0! Although the system had some rough edges, I liked it right from the beginning and became one of the ten Google Summer of Code students working on SilverStripe. For those who haven't heard of GSoC, here is a quick run-down:

  • Each year Google pays students to work on open source projects during the summer (of the northern hemisphere). This way they want to contribute back to the open source world as their systems depend on many such tools. And I would assume it is an image, and to some extent, a recruiting thing as well.
  • During the first phase, open source projects apply - as did SilverStripe in 2007.
  • Once the participating projects have been selected, students can apply to work on specific tasks. These can either be provided by a project or students can make their own suggestions. In my case, I went through the list of participating projects and that is how I found SilverStripe. Back then only MySQL could be used so I volunteered to add support for additional databases, namely PostgreSQL and MS SQL.
  • After the selection phase of students, the hacking begins under the supervision of mentors from each project. As you might have guessed, I was lucky enough to be selected. While I was not able to completely finish my effort, it has still kicked off SilverStripe's current support of multiple databases.
  • Once the GSoC is over, the students should have learned a lot about real world, open source software and might even stick around their project — which has worked out pretty well in my case, don't you think?
  • On a side note; due to various reasons, 2007 has been the one and only GSoC for SilverStripe. Maybe we can change that with the 3.0 release and I would be more than willing to help out with it, but that is another story.

As one might expect, the documentation was pretty thin as was the number of relevant hits on Google at that time. SilverStripe was brand new so this was to be expected. However, this made using it more challenging than it really needed to be. While some accepted the challenge and learned much more than by reading tutorials, many others did not and simply gave up. Obviously, documentation is essential for the success and adoption of an open source project.

The Status so Far

Fast forward a few years and the situation has been much improved. Besides the growing official documentation, pages like SSBits or Balbus Design provided and still provide a wealth of tips, tricks, and how-tos. Nevertheless, the situation was not too beginner friendly as you had to do a little hunting for the relevant information - piecing different examples and approaches together. So inspired by Ingo Schommer's excellent book SilverStripe: The Complete Guide to CMS Development, I wrote SilverStripe 2.4 Module Extension, Themes, and Widgets: Beginner's Guide just a little less than a year ago — explicitly targeting newcomers. While I hope to have helped some beginners (by the way, you can grab the code and some samples at GitHub for free), the reach of a book is somewhat limited. People start playing around with a system, but if they get stuck (often because of missing or bad documentation) they are likely to give up before taking the next step of ordering a book and reading it. I strongly believe that we have to lower the entry barrier as much as possible.

The Future Projection

For the 3.0 release I want to focus on the official documentation. It is the logical starting point for newcomers and I am a big fan of having everything in a single place. So what do I have in mind / where can you and I help:

  • Beginners are most interested in step-by-step tutorials. While there are some of those, they start showing their age and will need to be revised with the release of SilverStripe 3. However, I am not only thinking about minimal updates, but probably bigger enhancements. Should we have more tutorials, should we structure them differently, could we think of a better and continuous example project, should we add more details or remove some unnecessary ones. While I do not have any final answers yet, I am constantly looking for different ways of improvement. If you have any ideas, please share them!
  • Advanced users are probably more interested in extensive descriptions of specific features, recipes, and of course the API documentation. By the way, have you already seen Sam's brand new GridField documentation? We need more of those complete, up-to-date descriptions, both for core features as well as upgrade instructions and other relevant areas. Think about mobile, HTML5, Ajax — have you done anything awesome and can show how this can be done in SilverStripe? Please share, add, and update!

So those areas are exactly where I want to get my hands dirty for the awesome (I am already sure of that!) SilverStripe 3 release.

So much about the short term future, but what about the long run? I am confident that SilverStripe has a bright future ahead. While it is already awesome, it is getting constantly better thanks to the hard work everyone is putting into it. Additionally the SilverStripe community is very capable and active, even though it could be a little bigger. While this might not be the most sensible criterion, still many people care a great deal about the "size" of a project. So how can we foster the community, besides having a great system (keep those bug reports and patches coming)? Firstly, publicity to get attention and, secondly, shiny themes, outstanding modules and documentation (who would have guessed it). That is where everyone can get active; write about your experience with SilverStripe, document how you accomplish your tasks, publish and maintain your modules, distribute dashing themes, etc. Let all of us make SilverStripe bigger and better!

While we are on the subject; what do I think is the main challenge in writing good documentation? On the one hand you need to find a good example. It should be easy to understand and fit the topic well without adding anything overly obscure or ignoring some important aspect. On the other hand, it should be both complete and concise. Complete so that people can fully understand the example as well as reuse it for their real-world requirements. Concise so that the essence can be quickly understood while not over-simplifying. Once you have found a good example (I am a big fan of real-world requirements), it is "just" a matter of writing everything down clearly. That should be easy - or probably not, but once you have started others can help you.

You are more than welcome in helping with the upcoming documentation efforts! If you are unsure where and how to start, simply get in touch with me. My email is pk@xeraa.net.

Post your comment

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

Comments

  • "Beginners are most interested in step-by-step tutorials."
    "Advanced users are probably more interested in extensive descriptions of specific features, recipes, and of course the API documentation."

    I disagree. When I was a beginner, I LOVED jQuery's API docs (and I still do). I have /never/ used any other offical jQuery docs than the API docs.

    If you want an example of API documentation done RIGHT, look at jQuery's:
    http://api.jquery.com/addClass/

    Compare to SS's:
    http://api.silverstripe.org/2.4/sapphire/filesystem/Upload.html

    Posted by Nathan J. Brauer, 3 years ago @NathanBrauer

  • Phillip,

    I agree with the ideas Jose has given, especially the idea of a "big" web project tutorial.

    One framework that I found to have excellent docs was symfony, during their 1.x releases. They had a 24-part series of building a job board from scratch, and it exercised all parts of the framework.

    And Django always had decent docs, though I haven't seen them in a while. One CMS that always struggled, though, was Plone. It always felt like their docs were scattered and haphazard, and there seemed to be a lot of disagreement on the doc mailing list.

    And one last example, when Microsoft's MVC 2 came out, they had a 100+ page tutorial that walked through building a website.

    I'll try to pitch in once the beta comes out.

    Alex M.

    Posted by Alex M, 3 years ago

  • Thanks for the feedback!
    We'll try to keep it in mind. It's probably hard to provide examples for the whole API, but we'll add more examples of how to put it all together :-)

    Posted by Philipp, 3 years ago @xeraa

  • Hi Phillip,

    I have been working through both your book as well as Ingo's book and have found the material, tutorials and examples priceless. It has really helped me develop in Silverstripe. I am very excited to see that the Silverstripe framework is now being released separately and after looking at Cakephp and comparing that with how Silverstripe aproaches MVC i must say that i appreciate the work that you guys have been doing even more.

    If there is one thing that i would like to see in your next book is more information on how the API works/ how to use the API, maybe it is just me or maybe i missed something in the books but i don't always understand how to apply the info in the API documentation eg.. can the code be used in the view, or in the model or controller or all of the above.

    Php.net for example will show you the api and then an example to illustrate how it works. It makes it easier for a novice like myself to understand the practical implications of using the code.

    Anyway... thanks for the awesome work

    Posted by Shaun, 3 years ago

  • Hello Philipp,

    I completely agree with you.
    The main SilverStripe tutorial should be a big web project with all the basic features of a modern web, auto-rotating images, video, image galleries, news, blog, forum, user statistics, contact form, registry form, login form, shopping cart, searching, page layout ( grid systems, ...), PDF invoice, Internationalization, newsletters, protected download pages, mobile Web, RSS, Facebook, Twitter, Tuenti, Myspace links, and so on.

    The more extensive and detailed, new users can easily start creating their own websites and more easily will become famous SilverStripe.

    FAQ Area (common problems in the installation, CMS management, image upload, ...).

    A more detailed API documentation with examples.

    The essential modules (blog, forum, shopping cart) should be improved enough to cover most current requirements.

    Special page with all the SilverStripe 3 news with links to documentation that explains in detail and with examples all the improvements.

    Detailed special documentation to upgrade from SilverStripe 2.4 to SilverStripe 3.

    The documentation should be ready for the release of SilverStripe 3.

    Regards,
    Jose A.

    Posted by Jose A, 3 years ago

  • I've written some documentation guidelines a while back for anybody that wants to get started: http://doc.silverstripe.org/sapphire/en/misc/contributing#writing-documentation - yay for meta documentation ;)

    Posted by Ingo, 3 years ago @chillu

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.