Quatre types de documentation sont répartis selon deux axes : pratique-théorie et formation-travail.
Deux articles sensationnels sont sortis récemment :
Et beaucoup ont demandé : « Quelqu'un s'il vous plaît, enseignez-moi comment rédiger une bonne documentation ».
Je ne prétends pas être un expert, mais je pense que je suis bon dans ce domaine.
J'ai bu assez de café et je vais essayer d'expliquer ce que je sais.
TL ; DR : écrivez de la documentation pour résoudre un problème spécifique pour un groupe de personnes spécifique, pas seulement pour avoir la documentation.
Bien écrire
Tout d'abord, vous devez être doué pour l'écriture. L'auteur de Drunken Revelations a clairement nié cette affirmation, mais pour la plupart, cela peut ne pas fonctionner. Vous devez être capable de prendre des sujets et de trouver le point principal, de montrer les détails clés. Ces détails doivent être correctement séquencés puis traduits en phrases claires.
Une bonne écriture n'est pas seulement une question de documentation, bien sûr. Vous pouvez tester vos capacités dans ce domaine avec n'importe quel type d'écriture. Pouvez-vous écrire comment trouver quelque chose dans votre maison? Pouvez-vous écrire un court discours? Si vous avez besoin de travailler dans ce domaine, je vous suggère de vous entraîner à écrire autre chose que de la documentation. Écrivez des articles de blog, écrivez des histoires courtes, écrivez des lettres à des amis, peu importe. Si vous ne lisez pas régulièrement des livres, commencez dès maintenant. Votre cerveau doit être entraîné sur beaucoup de texte bien écrit avant de pouvoir dire ce qui fonctionne et ce qui ne fonctionne pas dans votre cas particulier. Développer une compétence d'édition qui est très différente d'une compétence d'écriture (l'écriture devient plus facile,si vous faites confiance à vos compétences d'édition - vous ne vous filtrerez pas autant).
Le conseil le plus utile pour rédiger de la documentation est d'écrire dans un style conversationnel. Il est beaucoup plus facile de percevoir des informations à partir d'un texte informel.
Types de documents
Bon, revenons maintenant à la documentation.
Il existe différents types de documentation, et les gens se fabriquent des cordes, essayant d'obtenir un type de documentation pour faire le travail d'un autre. L'étirement suit deux axes :
- Informations pour la formation VS informations pour le travail.
- Étapes pratiques VS informations théoriques.
(Ce n'est pas ma pensée, j'ai vu ça sur https://documentation.divio.com/ )
Les informations de formation contenant des étapes pratiques s'appellent un didacticiel. S'il ne contient aucune étape pratique, il s'agit d'une explication. Les deux ont tendance à être plus adaptés aux débutants, ils devraient donc se concentrer sur l'explication des concepts et des termes (et des informations de base). En termes d'explications, il est vraiment utile d'avoir un bref résumé en haut.
Il est prudent de supposer que, grâce aux informations sur le moment où vous travaillez, quelqu'un a déjà une idée générale de ce qui se passe.
L'information théorique utilisée dans le travail est appelée la référence. Cela inclut la documentation pour chaque méthode. La documentation d'aide est un endroit complètement inutile pour héberger un tutoriel.
Si ce n'est pas de la théorie, alors ce guide. Le guide est fondamentalement similaire à un didacticiel, avec deux différences importantes : il suppose une certaine familiarité avec le sujet et l'objectif est d'accomplir une tâche spécifique, pas d'enseigner. La liste de contrôle est un guide rapide, mais elle peut toujours être utile s'il est très facile d'oublier une étape importante. Utilisez les guides lorsqu'il y a des étapes que vous devez répéter. Ils sont particulièrement utiles lorsque la personne qui effectue les étapes ne sait pas comment accomplir la tâche (soit quelqu'un de l'autre équipe, soit vous dans un an).
Choisissez le type de documentation à rédiger en fonction des besoins de votre lecteur. Il se peut que votre code soit en fait assez auto-documenté et que la lecture de la signature de la méthode vous indique vraiment ce que fait la méthode. Excellent. Ceci est pour la documentation de référence. Écrivez maintenant les trois autres types.
Si tout ce que vous avez est une documentation de référence, l'information sera un tas de faits aléatoires inutiles pour les lecteurs qui ne connaissent pas les bases. La documentation d'aide, c'est comme avoir une description détaillée des intersections lorsque les nouveaux lecteurs recherchent des cartes routières.
Je pense qu'il existe en fait un cinquième type de documentation : les fils d'Ariane. Ce sont de petits commentaires dans le code ou des notes dans les documents (ou même des messages d'erreur dans les linters personnalisés) qui indiquent aux lecteurs ce qu'ils doivent savoir. Vous pouvez écrire un petit commentaire avec un lien vers le ticket Jira expliquant pourquoi ce code est nécessaire, ou vous pouvez indiquer aux gens quelle commande exécuter pour corriger le bogue. Les miettes de pain sont vraiment faciles à ajouter aux documents et permettent de gagner du temps.
Pourquoi
Il est très facile d'oublier d'écrire sur des choses qui semblent évidentes. Bien sûr, comment nous créons un microservice, je n'ai pas besoin d'écrire pourquoi nous faisons cela. Mais vous en avez besoin.
C'est évident pour vous, mais pas pour le lecteur. Le raisonnement derrière les décisions nous semble vraiment évident parce que nous avons passé tellement de temps à y réfléchir.
Lorsque vous expliquez pourquoi vous faites quelque chose, vous êtes obligé de retracer mentalement les étapes qui ont conduit à la décision. Il s'avère que c'est aussi un excellent moyen de vous présenter certains sujets.
Si vous êtes coincé à essayer d'expliquer pourquoi, imaginez à quoi ressemblerait le monde si ce que vous documentez disparaissait soudainement. Qui se soucie de ce qu'ils voient ?
C'est encore mieux si vous pouvez expliquer la raison avec une histoire. Les gens sont vraiment doués pour traiter et se souvenir des histoires.
J'aime les autres commentaires dans la documentation. Par example. "Nous savons que ce n'est pas bon, et nous voulons vraiment que cela fonctionne comme X, mais cela nécessitera que l'équipe T mette à jour ses documents, et ils sont très débordés, alors nous vivons avec pour le moment." C'est le genre d'information qui rassemble tout dans la tête des gens et leur donne l'impression de comprendre ce qui se passe.
Sujets non techniques
Ce n'est pas parce que vous documentez un sujet technique que le lecteur n'a pas non plus besoin de connaître certaines choses non techniques. La raison pour laquelle c'est le cas est très grave.
Autres détails non techniques utiles, notamment :
- , (, -, , ).
- . « X , Y, Z»
- . « , , , ».
- , « , ...»
Les tutoriels sont destinés à familiariser les gens avec le sujet. C'est une très bonne façon de le faire parce que les gens apprennent mieux quand ils font quelque chose, plutôt que de simplement lire.
Les tutoriels demandent également beaucoup d'investissement (par rapport à d'autres types de documents). Les écrire n'a probablement de sens que si beaucoup de gens ont besoin d'apprendre un sujet. S'il ne s'agit que de quelques personnes, les rencontrer en face à face (ou de webcam à webcam) est probablement la meilleure utilisation du temps.
Le piège lors de l'écriture de tutoriels est d'essayer de tout expliquer. Résistez à l'envie de lister tous les détails techniques et toutes les exceptions aux règles établies. Vous voulez juste que vos lecteurs comprennent les mécanismes de base. De petits détails peuvent être laissés pour la documentation pour les personnes plus expérimentées.
De plus, très souvent, les didacticiels ne fonctionnent tout simplement pas lorsque quelqu'un essaie de travailler avec eux. Vous devez essayer les étapes que vous avez écrites (idéalement sur un nouvel ordinateur sans tous les composants déjà installés) pour vous assurer qu'elles sont complètes et fonctionnent réellement. Suivez ensuite les étapes la prochaine fois que quelqu'un aura besoin d'utiliser ce guide et voyez où il est bloqué.
Les étapes seront également obsolètes, alors assurez-vous d'écouter les personnes qui ont des problèmes avec elles.
Guides
Les guides ont tendance à donner un bon retour sur investissement. Passer 10 minutes à énumérer les étapes dans une liste à puces peut vous faire gagner une heure à réfléchir à ce qu'il faut faire ensuite.
Ceci est particulièrement utile lorsqu'il est difficile de comprendre quelles sont ces étapes, ou si une étape importante est facile à sauter.
Rédigez des guides lorsque vous venez de terminer le processus et que vous êtes motivé pour éviter de tout comprendre à nouveau.
Explication et aide
Pour être honnête, je ne suis pas sûr de la valeur de la documentation de référence du style javadoc. Bien sûr, si un million de personnes vont utiliser votre leçon, retroussez vos manches et documentez tout dans les moindres détails. Mais si ce n'est que votre équipe qui lit, elle saura déjà 99% de ce que vous pouvez écrire.
Les explications sont généralement plus utiles, surtout lorsqu'elles se concentrent sur l'explication des raisons. Si vous expliquez l'utilisateur et les contraintes techniques qui conduisent à la création d'un design, vous pouvez presque oublier d'expliquer le design lui-même - armé d'informations de base, quelqu'un peut le comprendre par lui-même en lisant le code. Vous pouvez (éventuellement) apprendre la structure simplement en lisant le code, mais il est difficile voire impossible d'en comprendre les raisons de cette façon.
Pratique de la documentation
La rédaction de la documentation prend du temps. Beaucoup de temps. Passer ce temps sur la documentation n'est pas seulement magique parce que quelqu'un dit "nous avons besoin de plus de documentation". Vous devriez prévoir du temps pour cela et passer des heures à écrire. Non, ce n'est pas la façon la plus amusante de passer le jeudi soir, mais vous devez le faire.
Ou pas? Vous ne devez rédiger de la documentation que lorsque cela est utile. Vous n'écririez pas du code juste pour écrire plus de code (ou peut-être que vous le feriez, mais je ne le ferais pas). Vous écrivez du code pour résoudre un problème spécifique. Vous devez également rédiger une documentation pour résoudre un problème spécifique.
Ce « quelque chose » peut être mis en œuvre afin d'aider les nouvelles personnes à dynamiser l'équipe, à réduire le facteur bus dans l'équipe, à éviter les erreurs dues à l'oubli d'étapes, à faire gagner du temps aux personnes lors de l'exécution d'actions, à fournir un contexte, à établir un accord, à écrire grossier mais important détails, etc Si vous ne savez pas pourquoi vous écrivez de la documentation, ne le faites pas. Une fois que vous savez pourquoi, sélectionnez la documentation appropriée pour le problème à résoudre.
S'il vous plaît, au nom de tout ce qui est saint, n'écrivez pas de documentation comme celle-ci :
/**
* @param customer The customer
* @param order The order
* @return The price
*/
public Price getPrice(Customer customer, Order order) {}
Ceci est inutile et apprend aux lecteurs à sauter mentalement les commentaires. Ils sauteront les commentaires qui contiennent en fait quelque chose d'utile. Si vous n'avez rien à dire, ne le dites pas.
La documentation, comme le code, doit être maintenue. Vous devez payer pour son stockage. Vous devez prendre le temps de le soutenir. Heureusement, cela revient généralement beaucoup moins cher que de maintenir le code. Quelques heures par mois suffisent pour lire l'intégralité du wiki et corriger ce qui ne va pas en ce moment.
Astuce : Créez une section « archives » dans votre documentation et déplacez-y les documents obsolètes. Il préserve le contexte historique, c'est mieux que de simplement supprimer la documentation, et il n'a pas besoin d'être trompé par des lecteurs peu méfiants.
Une façon de gagner du temps est de transformer d'autres travaux en documentation. Si vous devez expliquer à un collègue comment intégrer votre système, copiez ce que vous écrivez dans Slack dans un document. Si vous avez écrit la documentation du projet, copiez-en plusieurs sections dans la documentation et passez 10 minutes à la préparer. Chaque fois que vous avez besoin d'expliquer quelque chose à un relecteur dans une revue de code, expliquez-le avec un commentaire dans le code, pas un commit sur Github. Votre ticket Jira explique-t-il pourquoi la tâche doit être terminée ? Cool, copiez ceci et vous avez la documentation. (Si non, demandez au questionneur de l'écrire !)
Dites aux gens où aller pour poser des questions. Pour écrire « si vous avez des questions, vous pouvez nous contacter à # team-channel sur Slack » en 15 secondes environ. Cela peut vous faire gagner des heures si vous êtes confus. Assez bon retour sur investissement à mon avis.
Donc, le café s'épuise, donc je vais m'arrêter là.