Contribuer à la documentation Xdepo

1) Introduction

Comme pour tout projet de logiciel libre, contribuer à la documentation de Xdepo constitue un excellent moyen de supporter cet outil et d'assurer sa pérennité. C'est pourquoi cette documentation est construite de manière à faciliter les apports de tous et chacun, notamment parce que :

1. La licence pour la documentation est une creative commons , facilitant ainsi la réutilisation de l'information et les contributions multiples.
2. Seul le traitement de texte OpenOffice.org est nécessaire pour créer de la documentation.

Ce document ne constitue pas un guide pour rédiger de la bonne documentation, mais uniquement les quelques règles de base qu'il faut suivre pour se conformer aux méthodes de documentation Xdepo.

2) Outils à utiliser

Le seul outil qui est absolument nécessaire est le traitement de texte de la suite bureautique OpenOffice.org. La suite est disponible en français pour les plates-formes Windows, MacOS X, Linux, Solaris et FreeBSD. Vous pouvez utiliser l'une ou l'autre de ces plates-formes pour participer à la documentation de Xdepo.

La diffusion sur Internet de la documentation se fait en format HTML, produit à l'aide de l'outil Transfolio. Vous n'avez pas besoin de Transfolio pour simplement rédiger de la documentation ou modifier de la documentation existante. Toutefois, si vous voulez vérifier comment sera diffusée cette documentation, il peut être utile de télécharger et d'installer Transfolio.

Une fois que vous avez Transfolio, vous pouvez le démarrer et lui fournir, sur la page de départ, le chemin du dossier où se trouve la documentation Xdepo. Vous pourrez ensuite la naviguer à l'aide de Transfolio.

Transfolio est en cours de finalisation, et les outils pour générer un site statique ne sont pas tout à fait stabilisés. Dès que c'est le cas, nous ajouterons ici la procédure à suivre pour générer ce site statique et ainsi produire une version HTML portable de la documentation Xdepo.

3) Organisation des fichiers

La documentation de Xdepo se trouve dans le dossier documentation/docs des sources de l'application. Dans ce dossier, on trouve essentiellement des fichiers OpenOffice.org (*.sxw ) qui contiennent les documents sources. On y trouve également des sous-dossiers qui permettent de mieux organiser les différents thèmes abordés. Les fichiers ou dossiers qui débutent par le caractère _ sont ignorés par le système de documentation.

Ces fichiers et dossiers doivent respecter un certain nombre de règles :

• Tous les noms de fichiers doivent se terminer par les caractères _fr.sxw ou _en.sxw pour, respectivement, des documents en français ou en anglais. D'autres langues sont bien sûr possible, vous devez toujours utiliser les codes de langue officiels pour les suffixes de fichiers.
• Ne jamais utiliser d'espaces, de majuscules et de signes diacritiques dans les noms de fichiers et de dossiers.
• Faire en sorte que l'ordre alphabétique des fichiers dans un dossier corresponde à l'ordre normal de lecture du dossier, en utilisant des préfixes numériques, suffisamment espacés pour permettre l'insertion ultérieure de nouveaux documents sans modifier les noms de fichiers.
• Dans chaque dossier, il doit y avoir un fichier index_fr.sxw et index_en.sxw , qui contiennent la page d'accueil ou d'introduction du dossier.

Le fichier _template.sxw est particulier, il contient des instructions sur les styles à utiliser et sur la manière de les importer. Vous êtes fortement invités à le lire avant de contribuer à la documentation.

4) Structure d'un document

Tout document inclus dans la documentation OpenOffice.org doit suivre une certaine structure de base. Pour bien mettre en place cette structure, le plus simple est de copier un document existant et de le modifier. Cette structure de base est représentée par les éléments suivants :

• Dans les propriétés du fichier, renseigner la propriété Titre avec un titre court qui sera utilisé dans le système de navigation HTML (table des matières et menus déroulants).
• Dans les propriétés du fichier, renseigner la propriété Commentaires avec un résumé clair et concis du document. Ce résumé pourra être utilisé comme métadonnées dans les pages HTML générées.
• Toujours débuter le document avec un titre complet en utilisant le style Titre principal pour les documents normaux et le style Titre principal section pour les documents index_[langue].sxw que l'on retrouve dans chaque sous-dossier.
• Après le titre principal, inclure la date de création et la date de dernière modification (champ dynamique OpenOffice.org) dans un paragraphe de style Date . Le contenu est tel que celui-ci : 2005-02-11 / 2005-02-27.
• Après la date, renseigner le ou les auteurs du document, avec leur affiliation, en utilisant le style Expéditeur .
• Le reste du document est constitué du corps du texte.

Dans le corps du texte, il est essentiel de bien utiliser les styles Titre 1 , Titre 2 , etc. afin de constituer une tableau des matières cohérentes et de faciliter la navigation. Pour les autres styles, voir le document _template.sxw qui contient des instructions à cet égard.

5) Illustrations

L'ajout d'illustrations permet de rendre la documentation plus compréhensible, notamment les copies d'écran. Voici quelques règles à suivre :

• Toujours utiliser une image externe et non une image interne à OpenOffice.org. Pour ce faire, lorsque vous utilisez la fonction Insertion -> Image -> A partir du fichier... vous devez vous assurer que la case Lien est cochée.
• Toujours nommer vos images avec un code de langue, comme pour les documents texte, lorsque du texte est présent sur l'image, copies d'écran par exemple. Cela permet d'avoir la même image en plusieurs langues.
• Sauf exceptions, toujours centrer les images dans le texte.

Si votre image peut être produite en JPEG de manière efficace, vous pouvez insérer un titre et d'autres métadonnées à l'image en utilisant un outil tel que PixVue.

6) Documents maîtres

Le fichier _master.sxg est également particulier. Il s'agit d'un document maître OpenOffice.org qui inclus tous les autres documents afin de constituer un seul document de traitement de texte, que l'on peut ensuite exporter en format PDF pour impression. Éventuellement, d'autres documents maîtres seront constitués de manière à produire des versions contenant uniquement le guide utilisateur, le guide intégrateur ou le guide développeur.

Pour mettre à jour le document maître, vous devez effectuer les opérations suivantes :

1. Ouvrir le document dans OpenOffice.org
2. Dans le navigateur , ajouter le cas échéant les nouveaux documents à inclure ou supprimer ceux à exclure. Vous pouvez le faire en cliquant sur le bouton droit de la souris et en choisissant Insérer -> Fichier .
3. Dans le navigateur , mettre à jour les sous-documents en cliquant sur le bouton droit de la souris et en choisissant l'option Actualiser -> Tout .
4. Dans le corps du texte, mettre à jour la table des matières en cliquant dessus avec le bouton droit de la souris et en choisissant l'option Actualiser l'index .

Une fois ces opérations faites, vous autre un document maître à jour, que vous pouvez sauvegarder, exporter en PDF, imprimer, etc.