Rédaction des documentations

Pages Suivantes


  • 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


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.5   Relectures

Champ optionnel.

Permet de préciser qui a relu le document, et à quelle date.

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

Champ optionnel.

Précise le public cible du documents

1.3.8   Commentaires

Champ optionnel.

Commentaires sur le document

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.

capture_moinmoin.png

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
rcasys.giprecia.fr_2015-02-05_18-01-37.png

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

Catégorie Wiki

AdminDocs: Aide/Rédaction des documentations (last edited 30/07/2015 16:48:10 by NicolasJoubert1)