Rédaction des documentations
Pages Suivantes
| /Syntaxe Rest |
- Auteurs :
- NicolasJoubert
- ChristopheDubreuil
Version : 1.0
- Date de création :
04/02/2015
Modification : Pas de modification
Status : En cours d'écriture
- Relectures :
- Relu par :
- Non relu
- Validation :
- Validé par :
- Non validé
Destinataire :
Commentaires :
- Vie du document :
- 1.0 :
Version initiale
04/02/2015
Table des matières
1 Le cartouche
1.1 Fonction
C'est l'élément minimum et obligatoire de tout document écrit pour le recia. Il est là pour assurer l'identification, la validation et le versionning des documents.
1.2 Contenu
:Auteurs:
Christophe DUBREUIL
:Version:
1.0
:Date:
25 Mars 2009
:Status:
En cours d'écriture
:Relectures:
Relu par :
Christophe DUBREUIL le 1 avril 2009
:Validation:
Validé par :
Christophe DUBREUIL le 1 avril 2009
:Destinataire:
Toute personne voulant écrire la documentation RST.
:Commentaires:
:Vie du document:
1.0 ::
Date : 25 Mars 2009
Version initiale
avec sa suite
1.1 ::
Date : 31 Mars 2009
Version modifié
1.3 Description des champs du cartouche
1.3.1 Auteurs
Champ obligatoire.
Warning
Comme tous les outils rest ne semble pas gérer correctement la séparation de champs par virgule ou le point-virgule dans le champ "authors", on n'utilisera pas le mot réservé "Authors", mais plutôt "Auteurs"
* PrenomNom
1.3.2 Versions
Champ obligatoire.
Le système de versionning permet de garder toutes les versions d'un document. Cependant, il est essentiel de mettre en place un systeme de version et de la maintenir à jour dès lors qu'il est en production.
Le champ Version est obligatoirement unique.
Composition du champ version :
Ce champ est constitué de la manière suivante :
1.3.2.1 Le majeur
- Le premier chiffre représente la version majeure du document :
- "0" signifie "en cours d'écriture"
- "1" signifie "stable", première version
- "2" signifie "stable", seconde version
- Un changement de version majeur indique une modification profonde de la documentation :
- procédure complètement différente
- changement complet d'une organisation,...
1.3.2.2 Le mineur
Le second chiffre évolue a chaque mise à jour mineure de la documentation.
Une description des changements de la documentation doit être écris dans le champ Vie du document ( voir plus loin )
1.3.2.3 La variante
Le troisième chiffre, optionnel, représente la variante.
- La variante est utilisée lorsque la modification du contenu n'en change pas le sens :
- Correction de fautes d’orthographe
- modification d'une tournure de paragraphe.
Le changement de variante n'est pas soumis à un processus de re-validation de document. Il est inutile de remplir le champ Vie du document sur une évolution de variante.
1.3.3 Date
Champ obligatoire.
Contient la date de création du document. Le champ Vie du document permet d'avoir les informations sur les dates de modifications.
1.3.4 Status
Champ obligatoire.
- Le champ Status peut contenir :
- En cours de d'écriture
- En cours de validation
- En cours de modification
- En cours de relecture
- En attente de relecture
- En attente de validation
- Valide
- Obsolète
1.3.6 Validation
Champ obligatoire.
Le document ne peut être considéré comme exploitable tant qu'il n'a pas été validé. Les personnes aptes à valider varient en fonction des documents. Ce sont en général les chefs de projets ou les chefs d'équipes.
1.3.9 Vie du document
Champ obligatoire.
Ce champ permet de garder un historique commenté de toutes les modifications du document.
Il est impératif de le remplir à chaque évolution du document.
Il pourra être nettoyé lors des validations afin de conserver ce champ lisible et utilisable.
2 Processus de validation
- Un document doit obligatoirement être validé avant de pouvoir être utilisé en production.
- Toute modification de version majeure et/ou mineure d'un document entraîne obligatoirement un processus de revalidation.
- Les modification typographique ( variante ) ne nécessitent pas de revalidation.
Le processus est le suivant :
- Quelque soit le type de modification apporté à un document, on change obligatoirement
- la version
- la date
- Si les modifications ne sont pas que cosmétiques ( modification majeure ou mineure), on modifie également :
- la Vie du document
- le statut, en fonction de l'état.
Un document ne peut retrouver son statut de validé qu'après avoir été relu et validé par une personne autorisée à le faire.
Toute cette procédure est manuelle. Il est donc essentiel que chacun s'y tienne.
3 La table des matières
Elle est automatique. Il suffit d'ajouter .. contents:: Table des matières à l'endroit ou on veux l’insérer.
4 Les catégories
4.1 Utilisation
L'utilisation des catégories dans la page d'édition n'est pas adaptée à notre format d’écriture qui est le reStructuredText.
Le système ajoute dans votre page d’édition, le format suivant :
| Wiki |
|---|
----
[[Catégorie Wiki]]
|
Or le bon système est celui ci :
| reStructuredText |
|---|
------------
`Catégorie Wiki`_
|
4.2 Création
Error
Seul un administrateur du wiki peut vous créer une catégorie.
Pour créer une catégorie, il faut appeler la page selon l'exemple suivant, remplacer Aide par le nom de la catégorie que vous souhaitez créer :
| url: | https://rcasys.giprecia.fr/Catégorie Aide |
|---|
Cliquer sur Créer une catégorie
5 Ajouter une page au wiki
Hint
Pour une bonne utilisation du wiki et pour permettre une hiérarchie correct des pages, je vous conseil d’éviter complètement de créer des pages à la racine mais d'utiliser le système de sous pages.
Exemple :
Pour cette page,j'aurai pu la mettre directement à la racine du wiki c'est à dire https://rcasys.giprecia.fr/Rédaction des documentations mais point de vue hiérarchique cette page est destiné à être un complément d'information sur l'aide donc la vrai place de cette page est bien https://rcasys.giprecia.fr/Aide/Rédaction des documentations