Guidelines For Documentation Writers

The Documentation Team does not have an exhaustive style guide at the moment, but the GNOME Documentation Style Guide can be used as a starting point.

Types of Documentation

Basically, we write documentation for users and for contributors. Final documents for users can be found in the Documentation Set in the website, or locally, in the operating system, in DocBook format. The most recent documentation in DocBook format is in the Bazaar repository. Documentation for contributors is very specific and specialized so it is located in the sections assigned to each of the teams listed in the How to help gNewSense page.

General Guidelines

The following is a list of guidelines that apply to both Web site and system documentation.

TODO:

Guidelines For Website Documentation

We use MoinMoin for the website. If you would like to edit or create pages in the website you should read MoinMoin Documentation to become familiar with its features.

General

URL Format

User documentation located at Documentation is organized according to the system version. The following URL format is used to separate documentation:

/Documentation/DISTRO_MAJOR_NUMBER

For example, the URLs for gNewSense 2.x and gNewSense 3.x documentation are:

/Documentation/3
/Documentation/2 

Pages belonging to a particular version must be created as subpages of the appropriate version to encourage the good use of the breadcrumbs feature.

Creating Documentation For a New Version of The System

When planning a new major version of the operating system, MoinMoin CopyPage action can be used to generate the base documentation for a future version of gNewSense. The CopyPage action allows to copy a page with all its subpages and conserve the editing history.

For example, to generate gNewSense X documentation, the following page would be copied with all its subpages

/Documentation/3

And renamed to

/Documentation/X

Note that the CopyPage action is not enabled by default in MoinMoin and has to be activated in MoinMoin configuration file. This action requires access to the server, so it has to be performed by a gNewSense system administrator.

TODO

Guidelines For System Documentation

The default help viewer of gNewSense operating system is Yelp. This program reads documentation written in DocBook; you should get familiar with its elements if you want to write or modify the current documentation in that format.

The system documentation is available in the Bazaar repository in the docs branch. You need to get familiar with Bazaar too to be able to help in this field.

DocumentationTeam/Guidelines (last edited 2013-08-21 15:16:43 by HarryPrevor)