How to Participate in Documentation

From Mandriva Community Wiki

First of all you should:

1. subscribe to the mailling list Development/Tasks/Documentation#How_to_Contact_the_Team
2. ask for a doc svn account by Entering a new bug on the "Mandriva Build System" Product, and Component: "Accounts"
3. get a local copy of the sources Development/Tasks/Documentation#Where_to_Find_the_Documentation

Contents 1 Working Principles 2 The Different Tools 3 The Project Management Interface (SvnNav) 4 Work Flow 5 Instructions for Translators

[edit] Working Principles

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

1. 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)
2. Once the files are validated, all kinds of information is extracted from them: workflow, dependencies, etc.
3. 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 images in SVG format, you will also need inkscape (in distrib).

And a tool to take screenshots, be it the one of KDE, gimp, import...

[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@iceland.net</authorinitials>
	  <revremark>write</revremark>
	</revision>
	<revision>
	  <revnumber>2008.1</revnumber>
	  <date>YYYY-MM-DD</date>
	  <authorinitials>pingusa@iceland.net</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 email address in the <authorinitials> tag if you want to be responsible for a specific task and recieve reminders.
• Add tasks or remove them at will.

[edit] Instructions for Translators

1. Translating a module or updating it must be done only once the task has been attributed to you. See the workflow mechanism.
2. If the module you plan to translate is not available in the target language directory, you must ask the project manager to prepare the corresponding manual for translation.
3. Whenever you want to start translating a new module, or modifying an existing translation, always make sure the original is final.
   • for this simply check the workflow of the original in the svnnav interface.
   • It must show the task for technical proofreading (or simply "check") at least, has been completed.
4. To help you with updating a translation, you have two tools:
   • the "Structure Diff Report" in the svnnav translated module page tells you what elements have been updated in the original with respect to the translation. You can then easily compare the XML source files.
   • the "Diff Report" in the svnnav orginal module page shows a colored diff between previous release and current version.