KISS : garder la documentation technique simple
Le principe KISS appliqué à la documentation technique : architecture de l'information, réutilisation DITA et écriture de phrases simples et maintenables.
Faire une documentation aussi simple que possible, sans la rendre moins utile.
Ce que KISS signifie pour la documentation
Section intitulée « Ce que KISS signifie pour la documentation »Le principe KISS est un principe général d’ingénierie : tout objet matériel ou virtuel construit par l’homme est plus fiable, et plus facile à maintenir et à faire évoluer, si sa complexité est volontairement réduite.
Appliqué à la documentation technique, c’est une contrainte de conception plutôt qu’un style d’écriture : quel que soit le format, le rédacteur peut tout aussi bien construire un ensemble documentaire élégamment architecturé qu’une usine à gaz, et la différence se paie des années plus tard, au moment de le modifier.
Pourquoi la simplicité compte
Section intitulée « Pourquoi la simplicité compte »- Compréhension. Le lecteur consacre son effort au produit, pas à votre structure.
- Charge cognitive. Moins de renvois et de détours à garder en tête simultanément.
- Maintenance. La structure choisie aujourd’hui fixe le coût de toutes les modifications à venir.
- Moins de points de rupture. Chaque lien de réutilisation, chaque override, chaque exception peut casser en silence.
- Évolution. Le produit évoluera : les structures simples y survivent, les usines à gaz sont abandonnées.
KISS en pratique
Section intitulée « KISS en pratique »- Architecture de l’information
- Une place évidente pour chaque sujet, et aucune hiérarchie que le lecteur doive déchiffrer.
- DITA et réutilisation
- Ne réutiliser que ce qui est réellement identique. Chaque ConrefUn mécanisme DITA XML de réutilisation d'un bloc de contenu par référence : le contenu d'un nœud cible est remplacé par le contenu d'un nœud source à la compilation.Voir dans le glossaire → est une dépendance que l’on s’engage à maintenir.
- Rédaction
- Peu de styles et aucun override : c’est au format de porter la structure.
- Écriture
- Une idée par phrase, dans l’ordre où le lecteur agit.
- Maintenance
- Préférer une structure modifiable à un seul endroit, sans avoir à tracer ce qu’elle alimente.
Les écueils classiques : sous 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 →, des conref centralisés ou imbriqués trop profondément, décrits dans une architecture documentaire trop complexe ? ; sous FrameMaker, des styles et des overrides qui se multiplient jusqu’à rendre le document ingérable.
Avant / après
Section intitulée « Avant / après »Une procédure rédigée par quelqu’un qui ne l’avait pas encore comprise :
Dans l’hypothèse où l’utilisateur souhaiterait modifier les paramètres de configuration, il est recommandé que le service soit préalablement arrêté, à la suite de quoi le fichier de configuration pourra être édité.
La même consigne, une fois qu’il l’avait comprise :
Arrêtez le service avant de modifier le fichier de configuration.
KISS ne consiste pas à écrire au rabais. Il s’agit de retirer la complexité qui coûte un effort au lecteur sans rien lui apporter en retour.
La valeur ajoutée du rédacteur technique
Section intitulée « La valeur ajoutée du rédacteur technique »Une phrase simple est plus difficile à écrire qu’une phrase compliquée, parce qu’elle suppose d’avoir compris le sujet - c’est précisément pourquoi tester le produit mérite qu’on y consacre du temps.
C’est ce discernement qui fait le métier : décider ce qui peut être simplifié et quelle complexité tient réellement au produit, où la réutilisation fait gagner du travail et où elle ne crée que des dépendances, et quelles structures seront encore maintenables trois versions plus tard.
D’où vient le principe
Section intitulée « D’où vient le principe »C’est ce principe qui a prévalu à la conception des montres Swatch, dont le cahier des charges stipulait qu’elles devaient embarquer deux fois moins de pièces que leurs consœurs : moins chères, plus fiables et renouvelables à l’infini. Les Shadocks, eux, l’ont mis en exergue par antiphrase : Pourquoi faire simple quand on peut faire compliqué ?