2.5 Principes de rédaction documentaire
Le présent chapitre n’est pas exclusivement à destination des développeurs. D’où sa présence ici. Mais un minimum d’outils sont nécessaires pour modifier la documentation (cf. §3.31)
2.5.1 - Accessibilité (au sens compréhension et pas RGAA)
La documentation doit être lisible et accessible à tous. En conséquence, il ne faut pas hésiter à ajouter des liens vers des documents/ressources externes permettant ainsi d’utiliser une notion sans la détailler complètement.
2.5.2 - Chapitrage
Le chapitrage sert un objectif d’abstraction et vulgarisation :
- Le premier chapitre Conception générale s’adresse à des personnes ne maîtrisant pas les technologies employées dans la solution.
- Le second chapitre Conception détaillée s’adresse aux personnes maîtrisant ces technologies mais ne développant pas sur le projet.
- Le troisième (Guide du développeur) et le quatrième chapitre (Ops) sont dédiés aux développeurs.
D’un point de vue mise en forme :
- Les mots ou expression en gras sont des mots clefs permettant de rechercher visuellement un sujet dans la page (entre deux doubles étoiles).
- Les mots clefs ou anglicisme sont en italique (entre deux underscores).
- La numérotation des chapitres et le paramètre weight de chaque page doivent être cohérents entre eux.
- Le titre d’une page et le nom du fichier associés doivent être identiques.
2.5.4 - Automatisation
La date de mise à jour est un hook paramétré sur le checkout du dépôt (cf. §3.2).