Les trois niveaux de la documentation technique
Comparez les trois niveaux de maturité de la documentation technique - des notes informelles au contenu modulaire structuré - et découvrez ce qui distingue chaque niveau.
Définition
Section intitulée « Définition »Si l’on compare la documentation technique à un jardin, on peut la classifier selon les niveaux suivants :
Les trois niveaux de maturité de la documentation technique.
Les trois niveaux comparés
Section intitulée « Les trois niveaux comparés »Trois composantes distinguent les niveaux : le processus documentaire, l’équipe et les formats.
| Niveau 1 : la friche | Niveau 2 : le jardin à l’anglaise | Niveau 3 : le jardin à la française | |
|---|---|---|---|
| Processus | Pas d’utilisation de processus documentaire | Utilisation de processus documentaires fiables | Utilisation de processus documentaires fiables |
| Équipe | Création de la documentation par des équipes non dédiées | Création de la documentation par des équipes dédiées | Création de la documentation par des équipes dédiées |
| Formats | Utilisation de formats non adaptés ou utilisation incohérente de formats adaptés | Utilisation cohérente de formats adaptés, mais non structurés | Utilisation cohérente de formats structurés |
| Exemples de formats | Traitement de texte | Type FrameMaker | DocBookLangage de balisage XML sémantique destiné à la documentation technique, organisé en livres, chapitres et sections plutôt qu'en topics typés. Antérieur à DITA XML, il sert de point de comparaison habituel lors du choix d'un format structuré.Voir dans le glossaire →, DITA XMLUne architecture de rédaction structurée et modulaire, construite autour de la typologie concept/tâche/référence et de la réutilisation de contenu via conrefs et ditamaps.Voir dans le glossaire → |
| Modèle de contenu | - | Documentation par sujets | DITA XML structuré |
Les formats non adaptés à la rédaction technique sont par exemple les formats de traitement de texte, qui ne dissocient pas suffisamment la mise en page du contenu.
Les formats adaptés sont les formats de type FrameMaker, qui dissocient (relativement) la mise en page du contenu, mais ne sont pas sémantiques.
Les formats structurés sont les formats sémantiques de type DocBook ou DITA XML.
Ce qu’apporte chaque niveau
Section intitulée « Ce qu’apporte chaque niveau »- De la friche au jardin à l’anglaise
- Le stade du jardin à l’anglaise est déjà très satisfaisant et garantit qu’une information de qualité est fournie à l’utilisateur.
- Du jardin à l’anglaise au jardin à la française
- Celui du jardin à la française permet en outre à l’entreprise de mieux maîtriser son contenu et de réduire les coûts de production.
Où en est votre documentation ?
Section intitulée « Où en est votre documentation ? »Posez les trois questions sur lesquelles reposent les niveaux :
- Processus. Un processus documentaire fiable est-il en place ?
- Équipe. La documentation est-elle créée par une équipe dédiée ?
- Formats. Vos formats sont-ils adaptés et utilisés de façon cohérente ? Sont-ils structurés ?
Si la réponse à l’une des deux premières questions est non, ou si vos formats sont non adaptés ou utilisés de façon incohérente, vous êtes dans la friche. Avec un processus, une équipe et des formats adaptés mais non structurés, vous êtes dans le jardin à l’anglaise. Des formats structurés font passer au jardin à la française.