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