SOP 000-Documentation » Historique » Révision 28
Révision 27 (Patrice Nadeau, 2018-03-24 15:38) → Révision 28/67 (Patrice Nadeau, 2018-03-24 15:39)
# SOP 000-Documentation
Établir un style de documentation unifié pour les items suivants :
* Documents
* Présentations
* Wikis
{{lastupdated_at}} {{lastupdated_by}}
---
{{toc}}
## 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)
{{lastupdated_at}} {{lastupdated_by}}
----
{{toc}}
## 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:wiki#Redmine-Rouge|Redmine Rouge]])
<pre>
<pre><code class="c">
...
</code></pre>
</pre>
* XeTeX : Le module _lstlisting_ est utilisé. Des titres et emphases peuvent être utilisées.
<pre><code class="latex">
\begin{lstlisting}[language=xxx, title=yyy, emph=serveur]
ssh serveur
\end{lstlisting}
</code></pre>
#### Guillemets
Les "guillemets":http://en.wikipedia.org/wiki/Non-English_usage_of_quotation_marks#French (« & ») 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 : Elle 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 :
** *<notextile>*</notextile>* : pour des items ayant une description.
** *<notextile>#</notextile>* : 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_ : *<notextile>"titre":/attachments/do </notextile>*
* 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 :
* Redemine : Un lien sur un « issue »
* XeTex (_todonotes_ est utilisé)
<pre><code class="latex">
\todo[inline]{Texte de ce qu'il y a à faire}
\todo\missingfigure{Texte de l'image manquante}
</code></pre>
Une section DOIT aussi êtres ajoutée avant la toute fin du document :
<pre><code class="latex">
\newpage
\section{Todo}
\listoftodos[]
</code></pre>
### 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 <notextile>></notextile>
<pre><code class="text">
item
> Texte
</code></pre>
* XeTeX
<pre><code class="latex">
\paragraph{item :}
Texte
</code></pre>
_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":https://webstore.iec.ch/publication/3406
* *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](http://en.wikipedia.org/wiki/ISO_8601) :
"ISO 8601":http://en.wikipedia.org/wiki/ISO_8601.
* Date : 2014-08-24
* Heure : 13:28
### Notation
Les 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 :
<pre><code class="latex">
\SI{10000.01}{\micro\A}
</code></pre>
### Symboles
Les symboles sont fait de la façon suivantes :
|_. Symbole |_. Signification |_. HTML |_. Textile |_. XeTex |
| ≈ | Approximativement | <notextile>≈</notextile> | | \approx |
| ± | Plus ou moins (tolérance) | <notextile> ± </notextile> | | |
| > | Plus grand | <notextile> > </notextile> | | |
| ≥ | Plus grand ou égale | <notextile> ≥ </notextile> | | |
| < | Plus petit | <notextile> < </notextile> | | |
| ≤ | Plus petit ou égale | <notextile> ≤ </notextile> | | |
| o | octet (unité) | | o | \octet |
| Ω | Ohm (unité) | <notextile> Ω </notextile> | | \si{\ohm} |
| µ | micro (préfixe) | <notextile>µ</notextile> | | \si{\micro} |
### Unité de mesure
Les unités de mesure à utiliser :
> "Le _byte_ n'est pas une unité officielle.":http://en.wikipedia.org/wiki/Octet_%28computing%29
|_. Mesure |_. Unité |_. Symbole |
| Longueur | mètre | m |
| Masse | kilogramme | kg |
| Courant électrique | ampère | A |
| Donnés | bit | bit |
| Donnés | octet | o |
| Résistance | ohm | Ω |
| Capacitance | farad | F |
| Voltage | volt | V |
| Fréquence | hertz | Hz |
| Puissance | watt | W |
### Préfixes
#### Base 10
<table>
<tr>
<td style="text-align:center;"> Préfixe </td>
<td> Symbole </td>
<td> Notation </td>
<td> Représentation</td>
</tr>
</table>
| tera | T | 10<notextile></notextile>^12^ | 1 000 000 000 000 | </td>
| giga | G | 10<notextile></notextile>^9^ | 1 000 000 000 |
| mega | M | 10<notextile></notextile>^6^ | 1 000 000 |
| kilo | k | 10<notextile></notextile>^3^ | 1 000 |
| deci | d | 10<notextile></notextile>^1^ | 0.1 |
| milli | m | 10<notextile></notextile>^-3^ | 0.001 |
| micro | µ | 10<notextile></notextile>^-6^ | 0.000 001 |
| nano | n | 10<notextile></notextile>^-9^ | 0.000 000 001 |
| pico | p| 10<notextile></notextile>^-12^ | 0.000 000 000 001 |
#### Base 2
Pour les données informatiques (1024).
|_. Préfixe |_. Symbole |_. Représentation |
| tebi | Ti | 1 099 511 627 776 octets |
| gibi | Gi | 1 073 741 824 octets |
| mebi | Mi | 1 048 576 octets |
| kibi | Ki | 1024 octets |
## Référence
"How To Read Command Syntax":http://pcsupport.about.com/od/commandlinereference/a/command-syntax.htm
"Les unités de mesure du système métrique - Le français sans secrets - Portail linguistique du Canada":http://www.noslangues-ourlanguages.gc.ca/bien-well/fra-eng/typographie-typography/metrique-metric-fra.html
"Office québécois de la langue française":http://www.oqlf.gouv.qc.ca/
"8e édition de la brochure du Système international d’unités":http://www.bipm.org/utils/common/pdf/si_brochure_8_fr.pdf
"Date et heures en français":http://servicesdedition.com/fr/langue/chroniques/coordonnees.html
"IEC_80000-13":http://en.wikipedia.org/wiki/IEC_80000-13
"IEEE 1541-2002":http://en.wikipedia.org/wiki/IEEE_1541-2002