How to Participate in Documentation

From Mandriva Community Wiki

First of all you should:

subscribe to the mailling list Development/Tasks/Documentation#How_to_Contact_the_Team
get a local copy of the sources Development/Tasks/Documentation#Where_to_Find_the_Documentation

1 Working Principles
2 The Different Tools
3 The Project Management Interface (SvnNav)
4 Work Flow

[edit] Working Principles

The whole system is based on scripts that are automatically activated whenever changes are committed to the SVN repository.

When a commit is done, the system starts checking whether the changes are valid, and all dependencies are available
- If all is fine the modified contents are moved to a specific "Validated" hidden repository
- Otherwise the file is tagged as invalid and reports are available in the SvnNav interface (see below)
Once the files are validated, all kinds of information is extracted from them: workflow, dependencies, etc.
Then the system crawls up the dependencies tree to check which publications (HTML or PDF) are affected by those changes, and regenerates such publications in http://neodoc.mandrivalinux.com/publications/

Note: After a commit you can follow the processing by looking at http://neodoc.mandrivalinux.com/

[edit] The Different Tools

You need a DocBook editor, for example:

emacs + nxml mode
XXE whose personal edition is free for editing free documentation
Conglomerate available in Mandriva but not fully tested yet

To edit schemas in SVG format, you will also need inkscape (in distrib).

[edit] The Project Management Interface (SvnNav)

The SvnNav Interface allows you to navigate through the sources repository and displays a variety of information useful for writers, translators, and project management:

You will find for each folder, the list of files it contains with additional information:

whether the file is valid DocBook and does not have missing dependencies (such as images) in the Status column
What the current task to be done on this module is.

When clicking on a file, a detailed status page displays with following information:

Access to validity and dependencies reports in case of problems
List of translations of this module if applicable
link to the original file if this is a translation
Link to changes page with respect to previous release, if applicable
link to structure diff with original module if applicable
Complete workflow
Change Log
List of dependencies (XML files or images included in this file)
List of object that use this object (reverse dependencies)

All this allows you to navigate by folder or by browsing the dependencies tree, thus allowing you to check all XML modules that are used in a document for example.

[edit] Work Flow

The workflow relies on a very basic system, based on the <revhistory> element of DocBook.

If you want to have a workflow in a XML module, you simply need to add a special revhistory element in the module top <info> element.

For example:

<?xml version="1.0" encoding="utf-8"?>
<book xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"xmlns:ns="http://docbook.org/ns/docbook" version="5.0" xml:id="DVD-Booklet" xml:lang="en">
  <info>
    <title>Introducing Mandriva Linux</title>
      <revhistory role="calenco:workflow">
	<revision>
	  <revnumber>2008.1</revnumber>
	  <date>2008-03-11</date>
	  <authorinitials>Peter</authorinitials>
	  <revremark>write</revremark>
	</revision>
	<revision>
	  <revnumber>2008.1</revnumber>
	  <date>YYYY-MM-DD</date>
	  <authorinitials>Pingusa</authorinitials>
	  <revremark>check</revremark>
	</revision>
	<revision>
	  <revnumber>2008.1</revnumber>
	  <date>YYYY-MM-DD</date>
	  <authorinitials>To Be Attributed</authorinitials>
	  <revremark>proofread</revremark>
	</revision>
      </revhistory>
      
......

So we have here a 3 step workflow:

Writing was finished by Peter on 2008-03-11
Technical accuracy check is current task and has to be done by Pingusa
The proofreader is not known yet

To change the workflow you just need to edit the XML code in the file, and commit to SVN:

Change YYYY-MM-DD to actual date on which date the work was completed
put your SVN login name in the <authorinitials> tag if you want to be responsible for a specific task.
Add tasks or remove them at will.

Retrieved from "http://wiki.mandriva.com/en/How_to_Participate_in_Documentation"