Umbraco 5 documentation on github
Anyone who has been part of the Umbraco ecosystem for more than a couple of days, have most likely been searching for documentation or samples. It has not always been easy to find, but I do believe that the situation has improved dramatically with our community wiki, umbraco.tv and all the starter kits available.
However, as we started on a clean slate with Umbraco 5, we also wanted to reboot documentation. We wanted to move away from the wiki model, and establish a more formalized flow for documentation, so we had a way to ensure structure, quality and uptodate code in the samples.
How do you solve that? Do you really want to build a workflow that can handle all this, or was there already something out there that we could leverage? Looking at what other open source projects have done in the past, a clever solution quickly presented itself.
On the bandwagon
Orchard and nuget (both are great .net projects) are storing their documentation as markdown files on github.com, allowing contributions through pull requests, that results in documentation that is simple to browse, read and contribute to, and we don't have to reinvent anything
So last week, inspired by these fine projects, we setup a Github repository, which will contain all future Umbraco 5 documentation. Documents are written using Markdown, and is very straightforward to get started with.
The best thing, about this setup, is that Github and git now handles our workflow and approval flow. If you want to submit or edit anything, simply fork the project, do your edits and do a pull request. For simple edits, you can even edit directly on github.com, or use Cloud9which is an online editor that integrates nicely with Github and git.
On a regular basis, we will then pull the latest changes to http://our.umbraco.org, index it for the site search and convert it into nicely formatted html, as it is a very simple format, we could at a later date also consider distributing documentation as .pdf or .mobi files
Be part of it
Work is progressing nicely, we have written the first batch of reference documents, and basic getting started guides. And best of all, we have received the first handful of pull requests from the community, for which we are very very grateful, keep them coming!
All frdays in March at the HQ are 100% dedicated to this project, so on friday (the 13th) you can join the umbraco room on jabbr and give us feedback, ask advice on how to get started, or just hang out.
The plan is to enable the the new documentation section Friday the 13th, it is still to be considered a preview / work in progress, but we want to share all the stuff that is already written, and inspire even more people to join in and contribute.
EDIT: As noticed, it is friday 16th, not 13th :) and also, we are in jabbr #umbraco room on all fridays so do stop by.
Also, we have a public trello board here that outlines the progress