SOP 000-Documentation¶
Établir un style de documentation unifié pour les items suivants :
- Documents
- Présentations
- Wikis
- Contenu
- SOP 000-Documentation
- Description
Termes¶
Les termes français équivalents au document RFC2119 seront utilisés dans les documents :
- MUST, SHALL, REQUIRED : DOIT (DOIVENT), REQUIS
- MUST NOT, SHALL NOT : NE DOIT (DOIVENT) PAS
- SHOULD, RECOMMENDED : DEVRAIS, RECOMMANDÉ
- SHOULD NOT : NE DEVRAIS PAS, NON RECOMMANDÉ
- MAY, OPTIONAL : PEUT (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¶
Chaque format est fait avec un langage de balisage différents :
Manuels et présentations : fichiers XeTeX (.tex)
Ils DOIVENT être exportés en format PDF.
Documents locaux : fichiers GitHub Flavored Markdown (.markdown)
Redmine : GitHub Flavored 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 | Markdown |
---|---|---|---|
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 : Les langages supportés sont ceux de CodeRay
```c code to display ```
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)
- Markdown : 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.
- \begin{xxx} ... \end{xxx}, xxx représentant:
Hyperliens¶
L’utilisation des hyperliens ce fait avec :
- Redmine : (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
- Les étiquettes sont faites selon cette convention (xxx:étiquette), xxx étant un des choix :
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 | XeTex |
---|---|---|---|
≈ | Approximativement | ≈ |
\approx |
± | Plus ou moins (tolérance) | ± |
|
> | Plus grand | > |
|
≥ | Plus grand ou égale | ≥ |
|
< | Plus petit | < |
|
≤ | Plus petit ou égale | ≤ |
|
o | octet (unité) | o | |
Ω | Ohm (unité) | Ω |
\si{\ohm} |
µ | micro (préfixe) | µ |
\si{\micro} |
Unité de mesure¶
Les unités de mesure à utiliser :
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¶
Symbole | Notation | Représentation |
---|---|---|
tera | T | 1012 |
giga | G | 109 |
mega | M | 106 |
kilo | k | 103 |
deci | d | 101 |
milli | m | 10-3 |
micro | µ | 10-6 |
nano | n | 10-9 |
pico | p | 10-12 |
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¶
Les unités de mesure du système métrique - Le français sans secrets - Portail linguistique du Canada
Office québécois de la langue française
Mis à jour par Patrice Nadeau il y a environ 2 mois · 2 révisions