WritingStandards

Validé le 26/07/2010

"Writing standards" for GLPI

La documentation de GLPI est basée sur Markdown qui peut utiliser plusieurs syntaxes différentes pour une même action.
Afin d'homogénéiser le code de la documentation, les syntaxes suivantes ont été retenues :

Titre

Souligner le titre avec le signe =

Titre de mon chapitre
=====================

Titre de mon chapitre

Sous-titre

Souligner le sous-titre avec le signe -

Sous-titre de mon chapitre
--------------------------

Sous-titre de mon chapitre

Liste

Ajouter un tiret en début de phrase pour indiquer le début d'une nouvelle liste.
Incrémenter pour ajouter une sous liste

- premier élément liste 1
- second élement liste 2
    - premier élement seconde liste
  • premier élément liste 1
  • second élement liste 2
    • premier élement seconde liste

Liste numérotée

Il suffit d'ajouter le chiffre de la puce avant le texte de celle-ci.

1. premier élément 
2. second élement
3. troisème élément
  1. premier élément
  2. second élément
  3. troisième élément

Italique

Entourer les caractères voulus d'un astérisque

premier *élément* liste 1

premier élément liste 1

Gras

Entourer les caractères voulus de 2 astérisques

premier **élément** liste 1

premier élément liste 1

Conseils

  • Privilégier les phrases courtes : sujet verbe complément.
  • Ce qui se conçoit bien , s'énonce bien
  • Une idée, un paragraphe.
  • Limiter les remarques ou les rassembler. L'abondance de remarques nuit à la lisibilité.

Règles

  • Les termes GLPI utilisées dans la documentation doivent être consignés dans le glossaire.
  • Utilisation de l'infinitif

Les actions, descriptions, titres de topics sont écrits à l'infinitif. Pas d'utilisation du "Vous". Pas d'utilisation de substantifs.

Exemple :

Pour télécharger GLPI, se rendre sur le site du projet et cliquer sur lien "Télécharger".

Exemple à ne pas reproduire :

Dans le menu X , vous trouverez et vous pourrez faire ....
  • Il s'agit de décrire les fonctionnalités d'une application donc parlons de l'application.

Exemple :

GLPI propose au sein du menu X les actions suivantes : ...

Quelques suggestions de formules

GLPI propose, présente, offre, permet, utilise, affiche, génère, compte, fourni, livre, montre.

Autres éléments

  • Dans une liste on sépare les lignes par un point virgule et on termine par point pour la dernière ligne.
  • Les éléments de menu GLPI ou à cliquer (dans le cas des tasks) doivent figurer en gras. Pour cela utiliser menucascade et uicontrol ;
    exemple pour un menu :
    <menucascade>
          <uicontrol>Configuration</uicontrol>
          <uicontrol>Authentification</uicontrol>
          <uicontrol>Configuration Authentification</uicontrol>
    </menucascade>
    

    exemple pour un élément à cliquer :
    Une action automatique nommée <uicontrol>Récupération des messages (Collecteurs)</uicontrol>
    
  • Les citations doivent figurer en italique.
  • Le code doit figurer en gras. Pour cela utiliser codeph ;
    par exemple
    Nom expression rationnelle vérifie <codeph>/DESKTOP_(.*)/</codeph>