Contribute to the Documentation

Documentation is a major part of the Umbraco project as it allows users and developers to come to grips with ins and outs of the system.  There is nothing more frustrating than trying to understand an API or feature when there is no official documentation explaining how it works! This was one of the reasons why the documentation project was created.  By helping contribute to the documentation project you are not only helping those that currently use Umbraco, but also the multitude of developers who are new to the platform.

The scope of this project is to provide overviews of concepts, tutorials, example code, and links to API references. It is always a work in progress, and we welcome valuable contributions from anyone willing to help. For details on how to contribute, see further down this page.

The documentation project lives at GitHub which provides an effective way of managing project documentation. To browse the documentation at GitHub visit: https://github.com/umbraco/Umbraco4Docs

What's in these guides

Stubs

This contains sample code files or "snippets" that you may find useful when building out your site. In Umbraco terminology, they are used for the "Razor Scripts" and "XSLT" editors. They are heavily commented, and will be available in the Umbraco release too when you create new macros or partials.

Documentation

Documentation is a collection of references and step-by-step guides, API references, Helper Class references as well as conceptual overviews of the architecture.

Contributing to the guides

To contribute to either the documentation or stubs, you can fork & clone our repository, make your edits, and simply push back your changes to gitHub and send us a pull request. All items that get pulled into the main repository will automatically get pushed to our.umbraco.org/documentation.

Getting started with Git and GitHub

For more details on the process, watch our video on how to contribute.

Repository organisation

So that we can target documentation for each release of Umbraco, there will be a branch for each released version. When making corrections or edits to documentation against one revision, if those updates are relevant to another release, merge those specific changes to the other relevant branches. No active work on the documentation should be done on the 'master' branch.

Contributing documentation

All documents are written in Markdown, using a simple structure and stored as .md files. These are then pulled to our.umbraco.org/documentation for easy browsing.

First fork and clone the repository so that you have your own working copy. Then choose the minimum version of Umbraco to which you know your edits apply. Then make your changes on the git branch for this version. Once you are happy with your edits, use github to issue a "pull request" which means your edits will be reviewed, and once accepted, merged into the main repository. Everything in the main repository will make it onto the our.umbraco.org/documentation site, which is why we have chosen a pull request workflow to keep everything simple and straightforward.

Contributing stubs

The code stub examples are written in Razor and stored as .cshtml files on in the git repository.

Planning & discussions

If you would like to get more involved in the discussions around the Umbraco Documentation project, please visit the following places:

Markdown conventions

Keep custom HTML to a minimum. All script and style mark-up are cleaned by default. For reference, the Markdown syntax guide is available.

Images

Images are stored and linked relatively to .md pages, and should by convention always be in an images folder. So to add an image to/documentation/reference/partials/renderviewpage.md you link it like so:

![My Image Alt Text](images/img.jpg)

And store the image as /documentation/reference/partials/images/img.jpg

Images can have a maximum width of 650px and maximum height of 600px. Please always try to use the most efficient compression,gif, png or jpg. No bmp, tiff or swf (Flash), please.

External links

Include either the complete URL, or link using Markdown:

http://yahoo.com/something

or

[yahoo something](http://yahoo.com/something)

Internal links

If you need to link between pages, always link relatively, and include the .md extension.

[Umbraco.Helpers](Umbraco.Helpers.md)

or

[Umbraco.Helpers](../../Reference/Umbraco.Helpers.md)

Formatting code

Indent your sample with a single tab, which will cause it to be rendered as <pre><code> tags. For inline code, wrap in ` (backtick) chars.

Use # for the headline, ## for sub headers and ### for parameters (on code reference pages)

For optional parameters wrap in _ (underscore) - end result: ###_optionalParameter_

Structure

For the documentation project, each individual topic is contained in its own folder. Each folder must have an index.md file which links to the individual sub-pages, if images are used, these must be in images folders next to the .md file referencing them relatively.