[Traduction] La documentation vous apprend 12 choses

Ce qui suit est une traduction libre du billet Twelve Lessons From Writing Documentation de Jeff Staddon, paru en novembre 2007.

Nous croyons tous qu’une bonne doc est importante, mais qui la fait réellement ? La documentation typique d’un système informatique d’entreprise consiste habituellement en un regroupements de notes, de quelques documents LISEZMOI abandonnés sur le partage réseau et peut-être de quelques lignes de commentaire dans le code.

Il y a quelques années, j’en ai eu assez du « processus de documentation » standard et j’ai commencé à réellement documenter ce que je faisais.

Voici ce que j’en ai retiré :

1. Comme toute compétence, pour écrire de la doc, on s’améliore avec la pratique. Au fur et à mesure que l’on s’améliore, cela devient de plus en plus amusant. (Oui, j’ai dit amusant. Cela peut vraiment être amusant).
2. Quelques uns des documents « classiques » (minimum requis par exemple) semblent avoir un temps de vie vraiment court. Les autres documents – étapes pour lancer un script compliqué – tendent à être très utilisés.
3. La doc est meilleur en petits fragments. J’utilise un wiki – cela facilite le type de « jet d’idée » rapide, c’est pourquoi les wikis sont très souvent le plus pratique. Ecrire en petits fragments préserve la tâche de l’ennui.
4. La doc doit être facile à mettre à jour. Autrement, elle sera périmée et perdra sa fiabilité. A nouveau, j’aime beaucoup le wiki pour cela.
5. On doit pouvoir chercher facilement dans la doc. Quelque chose qui est difficile à référencer — comme le format de document traditionnel utilisé sur le partage — ne doit tout simplement pas être utilisé.
6. La documentation est pour les développeurs et les utilisateurs, pas pour le management. Laissez la professionnelle (même s’il semble que le document sur le multi-threading est compliqué), mais cool.
7. Gardez la documentation réduite. Je préfère 1 ou 2 pages imprimées. Si un document est plus long que 3 pages, il couvre trop de sujets et peut être divisé en plus petites parties. C’est plus facile de naviguer dans des documents courts et il est plus facile de faire des recherches dedans (moins de fausses réponses). Appuyez vous sur la puissance des hyperliens !
8. Réduisez la documentation. Les systèmes sont naturellement hiérarchiques. Les systèmes se divisent en sous-systèmes, qui deviennent des classes, etc. Laissez la doc divisée de la même façon que l’architecture ou l’utilisation de votre système.
9. C’est pas grave d’avoir la document en dehors du code. La documentation qui est liée à une partie spécifique du code – documentant la classe et ses méthodes, par exemple – devrait être dans le code. Mais la doc sur le système et ses sous-systèmes fonctionneront mieux dans un wiki. La chose importante est que la documentation doit être facilement accessible et universellement reconnue comme le lieu où aller.
10. Tout la doc n’est pas relative au code. (Par exemple, un lexique des termes business ou acronymes). Il faut un endroit où stocker la documentation ne concernant pas le code.
11. La doc doit répondre aux questions sur « Quoi ? Où ? » et « Pourquoi ? ». Le code répond déjà à la question « Comment ? ». Pour ceux qui pensent que le code est « auto-documenté », essayé juste d’écrire du code qui explique pourquoi une conception ou une architecture a été choisie plutôt qu’une autre…Les commentaires les plus utiles sont ceux comme « nous essayons de faire…mais cela a semblé être une mauvaise idée parce que… »
12. La documentation doit être partagée. Plus de paires d’yeux la voient, plus elle devient valable.

Mais pour finir, la plus grande leçon – celui qui utilise le plus ma documentation est : moi. Je suis étonné de la fréquence. Je reviens lire quelque chose que j’ai écrit pour me rafraîchir la mémoire sur un certain système, processus ou autre. Le temps que j’ai passé à écrire a été facilement rentabilisé, juste pour le temps gagné à ne pas re-rechercher.