Aide à l'écriture de la documentation pour Plume-CMS

Recommandations pour les rédacteurs de la documentation

La documentation que vous écrirez sera lue par un certain nombre de personnes pour qui le concept de CMS est acquis. Mais d'autres auront des connaissances sur Internet très limitées. C'est ce qui constitue toute la difficulté de l'écriture d'une bonne documentation, proposant les bonnes informations à l'utilisateur. Vous trouverez ici une liste des petites choses qu'il faudra prendre en compte lors de la rédaction :

• Mon orthographe est-elle correcte ?
• Mes phrases sont-elles claires ?
• Est-ce que j'essaye bien de me mettre à la place d'un novice lorsque j'écris la documentation ?
• Est-ce que je discute avec les utilisateurs et les développeurs sur les manières d'améliorer la documentation ?
• Ai-je moi-même une bonne compréhension du sujet sur lequel j'écris ?

Ce sont les exigences fondamentales à satisfaire pour rédiger la documentation. Vous aurez aussi besoin de quelques compétences informatiques.

• Utilisation de subversion. Vous pouvez consulter le manuel de référence.
  • Les utilisateurs de Windows seront heureux d'adopter TortoiseSVN.
  • Linux (et par extension, Unix) possède une interface en lignes de commande et plus probablement une interface intégrée à votre éditeur de texte favori.
• Savoir écrire un fichier texte avec le jeu de caractères utf-8.
  • Sur Windows, il semblerait que vous pouvez le faire avec Context.
  • Sur Linux, votre distribution utilise normalement utf-8 de manière native.

Avec ça, vous êtes prêt à contribuer à la documentation !

Pas à pas

Avant toute chose, vous devrez effectuer une copie de travail (ou checkout) du contenu du site :

svn co https://login@svn.sourceforge.net/svnroot/pxsystem/website plume-website

N'oubliez pas de remplacer la mention login par votre identifiant Sourceforge. Cette manipulation va créer un dossier plume-website avec le contenu du site.

Structure du site

Il est aussi possible de consulter le contenu du site directement via le dépôt Subversion. Vous remarquerez qu'il existe un fichier participate.cms.txt, de même que la page participate.html sur le site web. En fait, les pages en .cms.txt sont converties par le microCMS en pages .html. Les autres fichiers sont copiés sans conversion.

La structure de base est simple.

A la racine du site se trouve la version anglaise, et nous plaçons chaque traduction dans des dossiers nommés à partir des deux lettres du code ISO de la langue. Par exemple, fr pour la traduction fançaise et de pour l'allemande.

Si vous effectuez une traduction dans un langue donnée, suivez juste la même structure que pour la version anglaise. Par exemple, si vous avez traduit en français la page anglaise /docs/plugins.html, mettez-la dans /fr/docs/plugins.html. Notez que le chemin relatif après la mention fr est le même. C'est important de respecter cette marche à suivre, ainsi, les liens sont facilement créables de la version anglaise aux versions traduites.

Comment écrire un fichier .cms.txt

Ouvrez-en un et jetez-y un oeil. C'est extrêmement simple. Le format du fichier est de la forme :

mot-clef: Contenu sur une ligne
mot-clef2:
Contenu qui prendra plusieurs
lignes. Une série de 3 '+' signifie 
que l'on clos le contenu.
+++
content:
Le mot-clef 'content' est spécial 
et doit être le dernier.

Quelques mots-clefs spécifiques :

• title: Le titre du document.
• date: La date de création de la forme AAAA-MM-JJ.
• author: La liste des auteurs, séparés par une virgule.
• description: La description du document.
• content: Le contenu du document au format wiki.
• template: Le gabarit de la page. Vous pouvez consulter les gabarits disponibles. Le gabarit par défaut est template qui charge le fichier template.php. Vous y trouverez aussi le gabarit homepage qui est stocké dans le fichier homepage.php. Les gabarits spécifiques aux traductions sont de la forme XX-template et XX-homepage où XX sont les deux lettres du code ISO de la langue.