Révision 3 - Historique - SOP 000-Documentation - SOP 000-Documentation - SOP - Patrice Nadeau

Actions

Historique

SOP 000-Documentation » Historique » Révision 3

« Précédent | Révision 3/67 (diff) | Suivant »
Patrice Nadeau, 2015-04-19 09:48

h1. SOP 000-Documentation

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

Documents
Présentations
Wikis

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

h2. Généralités

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

h3. 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 "Textile":http://txstyle.org/

h1. Description

> Explication supplémentaires (si nécessaires)

{{lastupdated_at}} {{lastupdated_by}}

----

{{toc}}

h2. Premier titre

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

h3. Typographie

h4. 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{...} | @-...-@ |

h4. 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)

...

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}

h4. 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{}

h4. Police

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

h3. Images

Les images DOIVENT être de format PNG

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

h2. Documents

Conventions utilisées dans les documents.

h2. 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).

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

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

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

h3. 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é)


\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[]

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

h3. Standards

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

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

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

h3. 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 :


\SI{10000.01}{\micro\A}

h3. 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é) | Ω | | \Omega |
| µ | micro (préfixe) | µ | | \micro |

Avertissement

Certains symboles ne sont pas générés en format PDF à partir de Redmine.

h3. Unité de mesure

Les unités de mesure à utiliser :

h3. Préfixes

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

h4. Base 2

Pour les données informatique.

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

Fichiers (0)

Mis à jour par Patrice Nadeau il y a presque 10 ans · 3 révisions

Projet

Général

Profil

Wiki

SOP 000-Documentation » Historique » Révision 3