Comprendre la documentation

Principes fondamentaux, terminologie et approche centrée sur l'audience pour qui débute en rédaction technique — ou souhaite affiner sa pratique.

1 min de lecture

Voir en Markdown

Commencez ici si vous découvrez la rédaction technique, ou souhaitez revenir aux principes qui sous-tendent tout le reste de ce manuel : pourquoi investir dans la documentation, d’où vient la maturité documentaire, ce qui distingue la rédaction de la Communication techniqueLa discipline plus large qui couvre tout le cycle de vie du produit et touche le grand public, les prospects et les journalistes — par distinction avec la rédaction technique, qui produit la documentation produit destinée aux utilisateurs après la vente.Voir dans le glossaire →, et comment la typologie de l’information structure le contenu.

Aperçu de l'argumentaire économiqueModèles de maturité, coûts d'outillage et retour sur investissement documentaire — l'argument pour investir dans un meilleur processus.

Les trois niveaux de la documentation techniqueSituez où se trouve aujourd'hui la pratique documentaire de votre organisation — de la friche au DITA structuré.

De la rédaction à la communication techniqueEn quoi cette discipline diffère du marketing et de la rédaction générale, et pourquoi cette distinction compte pour la conception du processus.

Typologie de l'informationLe socle architectural : Concepts, Tâches et Références, leur articulation avec DITA, et leur application dans nos modèles de rédaction.

Le principe KISSPourquoi la solution la plus simple qui résout le problème l'emporte sur la plus astucieuse, et comment cela s'applique à la documentation.

Comment la suite du manuel s’appuie sur ces bases

Les sections suivantes forment une progression. Une documentation n’est maintenable que si elle est structurée : l’information structurée et le contenu modulaire viennent donc en premier. Des sources modulaires au format texte peuvent être gérées dans Git comme du code, ce qui rend possibles l’automatisation et la CI/CD. Un contenu structuré et généré automatiquement peut enfin être publié sous une forme lisible par machine, pour des scripts, des moteurs de recherche et des assistants IA autant que pour des lecteurs humains.

Une fois ces bases acquises, poursuivez avec la construction d’un processus documentaire ou passez directement à la boîte à outils pratique pour des modèles et check-lists. Pour le choix de format fondamental, voir choisir un modèle de rédaction. Pour les termes techniques, voir le glossaire.