Actions

Historique

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 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

Ils DOIVENT être exportés en format Portable Document Format.
- Internes : XeTeX
- Externes (partagés avec d'autres) : OpenDocument
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.

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

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 :

Le byte n'est pas une unité officielle.

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