More stories
Share

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.

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

Watch a video on how to contribute on github here

The documentation project on github

Next Story

CG12 Session - My First V5 Website

If you don't know Umbraco, here are some numbers behind the world's friendliest CMS

One of the biggest benefits of using Umbraco is that the community is incredibly pro-active, extremely friendly and helpful.

Chances are that if you get an idea for something you would like to build in Umbraco, someone has already built it. So it is very likely that you can get good and friendly advice from someone from the Umbraco community on Our - just ask.

Number of active installs
409.219
Number of active members in the community
220.022
Known free Umbraco packages available
320

Want to be updated on everything Umbraco?

Be one of the first to know about special offers on our products and services. Get invitations to Umbraco events and festivals sent directly to your inbox.

All you need to do is get on our mailing list and soon you'll become a true Umbraco-know-it-all.

Sign up for our monthly newsletter

Are you sure, that's your real e-mail?