|
Une bonne documentation est précise, complète, compréhensible et maintenable. Il communique efficacement les informations nécessaires à son(ses) public(s) cible(s) et les aide à atteindre leurs objectifs. Voici une liste des qualités clés :
Précision :
* Exactité des faits : Les informations présentées doivent être vraies et à jour. Des informations obsolètes ou incorrectes sont pires que l’absence de documentation.
* Cohérence : La documentation doit utiliser une terminologie, un style et un formatage cohérents.
Exhaustivité :
* Couvre tous les aspects pertinents : Comprend toutes les informations nécessaires pour que le public visé comprenne et utilise le sujet documenté. Cela peut inclure la configuration, l'utilisation, le dépannage, les limitations et les concepts associés.
* Détails suffisants : Fournit suffisamment de détails pour être utile, en évitant toute brièveté inutile ou toute verbosité écrasante. Le niveau de détail doit être adapté au public cible.
Compréhension :
* Clarté et concision : Utilise un langage clair et simple, en évitant le jargon ou les termes techniques sauf si cela est absolument nécessaire (et en les définissant ensuite).
* Organisation logique : Les informations sont présentées de manière logique et facile à suivre, souvent à l'aide de titres, de sous-titres et d'aides visuelles.
* Bien structuré : Navigation facile et recherche rapide d'informations spécifiques (par exemple, via des index, des tables des matières, des fonctionnalités de recherche).
* Adéquation au public : Rédigé à un niveau de compréhension adapté au public cible (débutant, intermédiaire, expert).
Maintenabilité :
* Facile à mettre à jour : La documentation doit être facile à mettre à jour et à jour à mesure que le sujet documenté évolue. L’utilisation d’un système de contrôle de version est fortement recommandée.
* Modulaire et réutilisable : Les composants de la documentation peuvent être réutilisés dans différents contextes.
* Utilise un format gérable : Choisir le bon format (par exemple, Markdown, reStructuredText, un wiki) est important pour faciliter l'édition et le rendu.
Autres aspects importants :
* Accessibilité : La documentation doit être accessible aux personnes handicapées, conformément aux directives d'accessibilité.
* Exemples et illustrations : L’utilisation d’exemples, de diagrammes, de captures d’écran et d’autres aides visuelles peut améliorer considérablement la compréhension.
* Fonctionnalité de recherche : Si la documentation est volumineuse, il est crucial de fournir une fonction de recherche robuste.
* Gestion des versions : Indiquer clairement la version du sujet documenté.
Bref, une bonne documentation anticipe les besoins de ses utilisateurs et les aide à réussir leurs tâches. Il s'agit d'un investissement qui se traduit par une réduction des coûts de support, une satisfaction accrue des utilisateurs et une adoption plus rapide du produit ou du système documenté.
|
