Will is a senior developer at DNA Design, Wellington, New Zealand. He has been a contributor to SilverStripe since 2007, maintains several modules and is a well known face around the IRC and forum as willr.
I had the pleasure of attending the recent SilverStripe meetup in Wellington and listening to Cam Findlay's discussion on community engagement (if you weren’t lucky enough to join us there, I recommend you watch the videos). The night ended with an open Q&A between everyone about building community and how we can all help enhance the abilitiy for us to share collective knowledge and improve our community of practice.
The primary way to help share knowledge between lurkers, learners and old timers revolved around one elephant in the room - Documentation. “Sucks” was an oft-mentioned word, and frankly, I’m not even going to deny or defend that because documentation does suck for the most part.
Documentation is key to any software product, it’s how users understand what it is that they’re using, why they should use it and how they can use it to solve their problems.
SilverStripe’s documentation is the first point for the majority of newcomers to the product and a daily stop for the regulars. It should support, guide and show users first, how easy it is to get setup and start building nifty things quickly in order for them to dig into learning more. The more a user wants (and can) dive deeper, the further the docs should support as their primary reference. The responsibility of the documentation then, is critical. To guide people from learning and achieving the basic knowledge, all the way up to a point of understanding where they feel comfortable building awesome applications. That then feeds back into the user contributing through bug reports, patches, documentation modules, themes and IRC / forum support. Those contributions complete and benefit the entire eco system the the cycle continues.
How does the documentation currently fail at meeting those objectives? Well we can all list the reasons to hate it; it doesn’t cover enough material, hard to find the information you need, search is useless, content is out of date etc. Writing good documentation is hard, not impossible, but the responiblity needs to be shared, just like everyone helping out together in IRC, forums and stack overflow. Documentation is not [insert some other developers’] problem, it’s ours as a collective community of practice. We all work, play, live using this software. If I run into a problem and solve it, most likely that solution could help you, and likewise for you. Did you solve a problem like adding a new button to GridField? Awesome! Documenting that might just solve my problems.
If I had a nickel for every time I answered a forum post with a solution that wasn’t covered in the documentation, I’d be funding a trip halfway around the world by now. My fault, I'll take the blame for this one. I should (and trying to) make sure that if anyone asks a question on the forum, I ask myself the question “Where in the documentation do we talk about this?”. If I can’t think of one, perhaps I need to document it.
It may take less than an hour of mine (or your) time to quickly add a section to the docs but think that time may just help any of the other thousand fellow community members and potentially your future self. If you don't think you understand the solution enough to document, that offers a good chance to ask someone who might know, or raise a ticket. I'm sure I'm not the only one who is guilty of finding something out and not sharing that knowledge.
It’s easy to get carried away being ‘busy’ with ‘real’ work fixing client sites and making a living, but just like the rest of SilverStripe, bugs don’t magically get fixed, or features added in automatically by robots. Documentation is the collective result of individual people putting a bit of their time, effort and patience into improving things for everyone else.
Nearly 2 years ago we had bigger issues with the documentation. In fact, noone was updating the documentation. What came from a bit of research was the realisation that developers loved working with code, documentation not so much. They would submit code patches for new features, rewrite API’s or even remove things without considering the documentation wiki in the short term. As the wiki didn’t track the major updates (2.2, 2.3, 2.4), post or pre a major release, the content would exist in a disjoint state, stuck in gray matter between two different worlds of API revisions.
We needed a system that lowered the barrier to updating docs as much as possible for the people who write the most documentation. Developers love their code, so let's make documentation exactly like their code! Hence we moved everything to static markdown files, stored alongside the core, modules or themes in a ‘docs’ folder. This solved a lot of pains over the wiki concept, while introducing some new ones.
- Greater ease for code contributers to update code and documentation at the same time, thus keeping docs and code as close to being up to date as possible.
- New features could be added along with documentation in one hit. Pull requests could be checked for documentation, along with test coverage.
- Bundling docs next to code would leave greater exposure to affected documentation when renaming classes (find / replace) or introducing new API’s. Developers may consider where their feature will be documented.
- Docs automatically versioned / mergable (just like code).
- Docs available offline.
Although this system does have a few trade offs.
- Docs folder increases size of download (framework has 7mb of docs)
- No more wiki style editing. All editors need to have a github account / be a developer to contribute.
- Custom built doc.silverstripe.org, search engine. Long term support and time?
However, those trade offs weren't much of a deal breaker, they could be mitigated.
- Ingo discussed not including docs/ in the static download (only via git / developers version)
- Contributions from people who wouldn’t have a github account was crimially low on the old wiki (0.5-1% of lines changed). The increase in lines changed by developers now would likely more than offset the loss by non developers. You can also do simple edits for the wiki pages directly through the github interface (e.g https://github.com/silverstripe/sapphire/edit/3.0/docs/en/tutorials/1-building-a-basic-site.md for editing the 3.0 tutorials)
- Take the SilverStripe.org usability test to explain how to make the tools we all use better.
As one of the maintainers of the silverstripe-docs tool, I’m keen on futher reducing those tradeoffs with things like inline editing directly on doc.silverstripe.org for casual edits that syncs with github and redoing the search functionality to improve the experience of finding the content and making it easier to add content.
Let's space out again for a second, every single line of documentation currently online was written by a person much in the same position as you; each contribuion started by fixing one little thing. What our whole community is working off is over five years of little pieces of individuals. Have you ever noticed an issue in the documentation? Add a comment to the page, better yet submit a pull request, or request that someone with more experience should be brought in to explain.
As World Vision and other charities will have you believe; every little bit counts.
---
Documentation Discussion
https://groups.google.com/group/silverstripe-documentation
Documentation Requests
http://open.silverstripe.org/report/107
Fork the Framework and update the docs
https://github.com/silverstripe/sapphire
