Documentez le diable de tout.
Il y avait récemment un fil sur Slashdot sur le démarrage de la documentation, qui m'a inspiré pour écrire mes réflexions sur la documentation.
Mes points clés étaient:
Principe n ° 1: ce n'est jamais fait
La documentation est un effort continu qui sera toujours à la traîne de ce qui est en production. Les modifications sont apportées de manière ponctuelle, les choses sont déplacées, interrompues ou mises en service au hasard. La documentation ne rattrapera jamais.
Vous devez vendre aux personnes qui paient les factures la valeur du temps (et donc de l'argent) consacré à la mise à jour de la documentation en cours. Souvent, ces conversations se déroulent comme suit: "souvenez-vous quand j'ai dû passer $ TIME à comprendre comment $ THING a été cassé? Eh bien, quand j'ai fini, il y avait cette note technique détaillant $ THING, de sorte que le prochain gars à venir ne le fera pas doivent tout comprendre. "
Vous devez le faire, même si vous ne finirez jamais.
Principe n ° 2: la seule chose pire que l'absence de documentation est une mauvaise documentation
C'est plus un truisme qu'un principe. La documentation peut vous endormir dans le faux sens que quelque chose est dans un état connu et que si quelque chose ne va pas, vous pouvez donc commencer à le réparer.
Il est important de reconnaître ce problème.
Principe n ° 3: vous rédigez de la documentation pour votre successeur
Les chances sont de 95% de tout ce que vous documentez auquel vous n'aurez plus jamais à vous référer. La documentation est une collection de sagesse pour l'avenir, pas pour vous. Vous devez donc supposer que votre public ne sait pas ou peu de choses sur la façon dont les choses sont comme elles sont.
Et il y aura un successeur. Je ne sais pas pour vous, mais je ne prévois pas être dans ces environnements spécifiques pour le reste de ma vie. Les opportunités vont et viennent, et quand elles viennent, parfois vous allez. Mais la vie continue derrière vous, et plus vous pourrez améliorer la vie de votre successeur en douceur. Sinon, vous pourriez avoir une collection d'anciens clients qui disent tranquillement des choses peu flatteuses à votre sujet. J'aime dire que ce sont les 50 mêmes gars qui travaillent partout en TI à Ottawa parce que vous les rencontrez partout. Aider votre successeur pourrait vous ouvrir des portes à l'avenir.
Maintenant, dans une certaine mesure, il y a toujours un certain "blâme envers le gars précédent" lorsque des problèmes surviennent. Cela fait partie de l'entreprise. Je l'ai fait moi-même. Mais à plusieurs reprises, quand j'avais critiqué le gars précédent comme une sorte de crétin, j'ai appris autrement qu'il avait vraiment son acte ensemble et en savait plus sur ce qui se passait que moi à l'époque.
Principe # 4: "Pourquoi" est souvent plus important que "Comment"
Lorsqu'on regarde un système, la plupart d'entre nous commencent à penser comme pourquoi diable est-ce ainsi? Il y a presque toujours des raisons très spécifiques pour les choix de configuration effectués. Dans ces circonstances, le «pourquoi» dicte le «comment», et vous devez vous assurer que le lecteur comprend les problèmes spécifiques à résoudre lors de l'examen des restes de tabac de votre solution.
Principe # 5: Ça doit être facile ou tu ne le feras pas
Cela signifie que vous devez être très conscient de vos outils ainsi que de ceux qui vont utiliser vos outils.
La mise à jour doit être facile. Si vous devez faire un effort quelconque, vous trouverez des excuses pour éviter de le faire quand il est préférable de le faire, c'est-à-dire immédiatement après un changement.
Si vos outils ne sont pas faciles à utiliser pour les autres, ils ne les utiliseront pas. Cela peut être particulièrement invalidant dans un environnement d'équipe, car plus l'équipe est grande, plus vous rencontrerez de chances un membre de l'équipe qui n'aime pas votre choix d'outils.
Personnellement, j'aime un wiki pour les documents. Cependant le problème est qu'un wiki ne vous force pas sur une structure, donc la structure doit être imposée de l'extérieur. Cela mène toujours à un conflit quelque part car quelqu'un d'autre a une idée meilleure / différente.
Dans certains endroits, j'ai utilisé des documents Word et Visio "publiés" au format PDF, le "dernier" PDF faisant autorité. C'est bien car vous avez alors une collection que vous pouvez remettre à votre employeur / successeur. Les PDF, s'ils sont correctement datés, peuvent fournir un historique de ce qui s'est passé, bien qu'il ne soit pas facile de s'y retrouver. C'est mauvais en ce que je n'aime pas Word ou Visio et j'ai été obligé d'acquérir une compréhension de base de ces outils afin de communiquer efficacement les idées.
Mon employeur actuel joue avec l'idée de documents Word dans un portail Sharepoint. Il faudra juste voir jusqu'où on va