Actions

Historique

SOP 000-Documentation » Historique » Révision 41

« Précédent | Révision 41/67 (diff) | Suivant »
Patrice Nadeau, 2018-03-31 14:40

SOP 000-Documentation¶

Établir un style de documentation unifié pour les items suivants :

Documents
Présentations
Wikis

Termes¶

Les termes français équivalents au document "RFC2119":http://tools.ietf.org/html/rfc2119 seront utilisés dans les documents :

MUST, SHALL, REQUIRED : DOIT, REQUIS
MUST NOT, SHALL NOT : NE DOIT (DOIVENT) PAS
SHOULD, RECOMMENDED : DEVRAIS, RECOMMANDÉ
SHOULD NOT : NE DEVRAIS PAS, NON RECOMMANDÉ
MAY, OPTIONAL : PEUX (PEUVENT), OPTIONNEL

Ces termes sont utilisés pour indiquer un choix quand plusieurs options sont disponibles.

Généralités¶

La documentation DOIT être générée avec des outils « open-source ».

Formats utilisés¶

Il existe deux type de documentation avec chacun leur outils :

« stand-alone » : fichier XeTeX

Ils DOIVENT être exportés en format PDF.
« live » : wiki (Redmine)

L’écriture se fait :

Redmine : Écrit en format Markdown

Description¶

Explication supplémentaires (si nécessaires)

Premier titre¶

Sous-titre¶

XeTeX : Le contenu du fichier tex DOIT être fait de la manière suivante :
- Format : Lettre.
- Orientation : Portrait.
- Langue : Français
- Type : Article
- Format : UTF-8
- Lignes : longueur de 80 caractères
- Retrait : de 4 espaces dans les sections \begin{} ... \end(}
- Les gabarits déjà établis DOIVENT être utilisés.

Typographie¶

Type de caractères¶

|. Effet |. Signification |. XeTeX |. Textile |
| Gras | doit être indiqué comme tel | \textbf{...} | @...@ |
| Italique | doit être substitué par la bonne valeur | \textit{...} | @...@ |
| Emphase | emphase | \emph{...} | @...@ |
| -Barré- | non valide | \sout{...} | @-...-@ |

Code source¶

Le code source doit toujours être mis en évidence avec un outil de «syntax highlight»

Redmine : «class» étant : c, bash, latex, php (voir Redmine Rouge)
```
  <pre><code class="c">
  ...
  </code></pre>
```

XeTeX : Le module lstlisting est utilisé. Des titres et emphases peuvent être utilisées.

  \begin{lstlisting}[language=xxx, title=yyy, emph=serveur]
      ssh serveur
  \end{lstlisting}

Guillemets¶

Les guillemets (« & ») DOIVENT être utilisés dans les document français.

Il DOIT y avoir un espace entre les guillemets et le mot.

Ils sont faits de cette façon :

Redmine : Unicode U+00AB (171), U+00BB (187)

Sous GNU/Linux, il peuvent être fait avec la combinaison ALT-z et ALT-x en mode français (utiliser la touche ALT de droite).
XeTeX :
Ils DOIVENT être faits avec \enquote{}

Police¶

La police de caractère et son poids sont générés par Redmine et XeTeX.

Images¶

Les images DOIVENT être de format PNG

XeTeX : Elles DOIVENT être enregistrées dans le même dossier que le fichier .tex.

Documents¶

Conventions utilisées dans les documents.

Découpage du document¶

Sections minimum pour différents type de documents :

Documentation de logiciel (guides) :
- Introduction.
- Installation.
- Configuration.
- Utilisation.
- Problèmes connus.
- Todo (XeTeX).

Style¶

Le document est séparés au moyen de :

XeTeX : section, subsection et subsubsection (\section{} DOIT être précédée de \newpage)
Textile : h2. @ h3. (suivie d'une ligne vide)

La table des matières seras faites automatiquement avec ces items.

Chaque section DOIT commencer par une brève description.

Listes¶

Les listes sont faites avec :

Redmine :
- * : pour des items ayant une description.
- # : pour des « étapes ».
XeTeX :
- \begin{xxx} ... \end{xxx}, xxx représentant:
  - description : pour des items ayant une description.
  - enumerate : pour des «étapes».
  - itemize : le type le plus fréquent.

Hyperliens¶

L’utilisation des hyperliens ce fait avec :

Textile : (voir http://www.redmine.org/projects/redmine/wiki/RedmineTextFormatting)
- Documents : document#nb
- Files : "titre":/attachments/do
XeTeX : \label{}, \ref{}, \pageref{}
- Les étiquettes sont faites selon cette convention (xxx:étiquette), xxx étant un des choix :
  - chap: : chapitre
  - sec: : section
  - subsec: : sous-section
  - fig: : figure
  - tab: : table
  - eq: : équation
  - lst: : code
  - itm: : liste énumérée
  - app: : sous-section d’appendice

Items à faire¶

Les notes pour les items à faire plus tard DOIVENT être décrites comme suit :

Redmine : Un lien sur un « issue »

XeTex (todonotes est utilisé)

  \todo[inline]{Texte de ce qu'il y a à faire}

  \todo\missingfigure{Texte de l'image manquante}

Une section DOIT aussi êtres ajoutée avant la toute fin du document :

  \newpage
  \section{Todo}
  \listoftodos[]

Paragraphes spéciaux¶

Les items nécessitant une attention particulière de la part du lecteur, sont identifiés avec :

Redmine : un retrait fait avec > :
```
  item
  > Texte
```
XeTeX
```
  \paragraph{item :}
  Texte
```

item étant une des valeurs :

Note : explications non critiques sur un point
Avertissement : un point qui mérite une grande attention
Ex. : un exemple

Standards¶

Tableau¶

Un tableau est fait de la manière suivante :

La tableau et les cellules DOIVENT avoir une bordure
Les données DOIVENT être en ordre (alphabétique ou numérique, selon le cas)
La première ligne DOIT
- contenir le nom des colonnes
- être centrées
- en caractères gras

Couleurs¶

Abréviations selon IEC 60757

BK : Noir
BU : Bleu
BN : Brun
RD : Rouge
YE : Jaune
VT : Violet
GR : Gris
WH : Blanc
CL : Transparent

Ne fait pas partie du standard

Dates et heures¶

L’heure des documents généraux est inscrite en format français (xx h yy.)

Les documents technique eux sont inscrits dans le format ISO 8601 :

Date : 2014-08-24
Heure : 13:28

Notation¶

Règles d’affichage des nombres et des unités.

Les règles suivantes DOIVENT être utilisées :

le séparateur décimal DOIT être un point,
le séparateur pour les milliers DOIT être un (demi-)espace,
le nombre est suivit d’un (demi-)espace et du préfixe et de l’unité de mesure

Sous XeTex, l’utilisation de siunitx EST requise.
Ex. :

Pour avoir 10 000.01 μA :

\SI{10000.01}{\micro\A}

Symboles¶

Les symboles sont fait de la façon suivantes :

|. Symbole |. Signification |. HTML |. Textile |_. XeTex |
| ≈ | Approximativement | ≈ | | \approx |
| ± | Plus ou moins (tolérance) | ± | | |
| > | Plus grand | > | | |
| ≥ | Plus grand ou égale | ≥ | | |
| < | Plus petit | < | | |
| ≤ | Plus petit ou égale | ≤ | | |
| o | octet (unité) | | o | \octet |
| Ω | Ohm (unité) | Ω | | \si{\ohm} |
| µ | micro (préfixe) | µ | | \si{\micro} |

Unité de mesure¶

Les unités de mesure à utiliser :

Le byte n'est pas une unité officielle.

Préfixes¶

Base 10¶

Préfixe

Symbole

Notation

Représentation

| tera | T | 10^12^ | 1 000 000 000 000 |
| giga | G | 10^9^ | 1 000 000 000 |
| mega | M | 10^6^ | 1 000 000 |
| kilo | k | 10^3^ | 1 000 |
| deci | d | 10^1^ | 0.1 |
| milli | m | 10^-3^ | 0.001 |
| micro | µ | 10^-6^ | 0.000 001 |
| nano | n | 10^-9^ | 0.000 000 001 |
| pico | p| 10^-12^ | 0.000 000 000 001 |