Guidelines For Documentation Writers
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.
The following is a list of guidelines that apply to both Web site and system documentation.
- Don't abbreviate gNewSense to "gNS".
- Don't write in the first person.
- Assume that the reader has basic keyboard, mouse and GUI skills (understands Ctrl+O, dragging, selecting a menu item), unless those skills are the topic at hand.
- English: UK vs. US
- Uniform package installation method (apt-get, aptitude, Synaptic, ...?).
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.
- Do not put "gNewSense" in the page name; the full URI already contains "gnewsense.org".
Use the <<TableOfContents>> macro to create tables of contents for pages with a long list of sections.
- Make clear the version of the software you are writing about.
- Leave a comment when you edit a page.
User documentation located at Documentation is organized according to the system version. The following URL format is used to separate documentation:
For example, the URLs for gNewSense 2.x and gNewSense 3.x documentation are:
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
And renamed to
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.
Make (better) use of MoinMoin categories, in a structured way.
- Tag pages (sections?) that need work.
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.