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.
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:
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.
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.
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:
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 firstname.lastname@example.org.