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.
