Umbraco 5 documentation on github

Tuesday, March 13, 2012 by Per Ploug

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.

Rebooting documentation

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  Cloud9 which 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

Watch a video on how to contribute on github here

The documentation project on github

3 comment(s) for “Umbraco 5 documentation on github”

  1. Gravatar ImagePinal Bhatt Says:

    Gr8 initative..... was waiting for this since long. Lack of structured documentattion was the one and only biggest drawback for new commers to Umbraco.

  2. Gravatar ImagePreetham Reddy Says:

    This is great... but are you referring to Friday the 16th to join the team on jabbr? There is no friday the 13th in March 2012.

  3. Gravatar ImageAlex Norcliffe Says:

    @Preetham yep it's this Friday, 16th :)

Leave a comment