Documenter le projet EOLE

Une documentation est au minimum constitué des items suivants :

• un support ;

• un guide utilisateur ou une section isolée ;

• des sections ;

• des blocs et des parties.

Les items sont liés entre eux pour obtenir la documentation. On obtient plusieurs niveaux. Il est recommandé de ne pas faire trop de sous niveaux pour faciliter la navigation (documentation HTML) et la lecture (documentation PDF).

3 supports sont utilisés pour chaque documentation EOLE :

• un support de guide Guide web ;

• un support de guide Guide papier ;

• un support de référence Site de référence.

Les supports sont stockés dans Zz-guides-<versionEOLE>.

Les supports de guide ne doivent utiliser que des guides utilisateurs, en effet l'utilisation d'une section isolée ne permet pas l'affichage de la page de garde.

Un guide ne doit contenir que des sections.

Les sections permettent d'organiser l'information par thématique.

Des sections peuvent elles-même lier plusieurs sections, dans ce cas il est souhaitable d'ajouter une introduction dans un bloc texte.

Les parties sont à utiliser pour :

• structurer la documentation, apparition d'un sous menu dans la documentation HTML ;

• pour réutiliser la partie dans une autre section en l'externalisant.

Il existe des blocs de plusieurs nature pour mettre en évidence du texte en fonction de son contenu :

• bloc information ;

• bloc attention ;

• bloc exemple ;

• …

Le seul bloc proscrit est le bloc complément car le lecteur doit cliquer pour en afficher le contenu dans la documentation HTML et il peut passer à côté du contenu.

Le découpage est limité par deux règles :

• le titre d'une partie permet de générer un sommaire dans la doc HTML
• une partie peut contenir d'autres parties ;
• un bloc d'information ne doit pas avoir de titre (si le titre est nécessaire, opter pour une partie plutôt qu'un bloc), le titre de bloc n'est pas très visible mais il peut tout de même permettre de découper les paragraphes trop long par thématique.

L'explorateur placé sur le côté gauche de SCENARI client permet de naviguer dans l'arborescence des différents items.

Voici quelques règles de classement des items :

• un répertoire par version majeure d'EOLE (les documentations concerne la dernière toujours la sous version publiée) ;

• à chaque nouvelle version majeure les documentations sont portées et donc copiées au fur et à mesure (ceci pour éviter qu'une changement dans une doc pour une version donnée impacte une version antérieure ;

• le répertoire Zz-commun permet de stocké ce qui est commun aux différentes versions de documentation, en cas de portage d'une documentation les liens vers les parties communes sont préservées.