J'ai trouvé TOUTE documentation meilleure que AUCUNE documentation. Le montant approprié est généralement déterminé par le temps dont nous disposons pour le faire, ou par combien nous détestons les appels téléphoniques et les courriels.
Il semble que les membres actuels de votre équipe aient des attentes irréalistes vis-à-vis de leurs souvenirs, ou qu'ils aient honte de leurs compétences en écriture et ne soient pas disposés à pratiquer.
Je me rends compte que je suis en minorité (majeure en anglais qui s'est lancée dans le génie logiciel à l'université) ici, car je ne trouve pas la documentation comme une corvée. C'est un précieux outil professionnel. Je ne trouve peut-être pas l'écriture aussi difficile à faire que certains de mes collègues, mais c'est principalement parce que j'ai plus de pratique dans ce domaine. Je ne considère pas qu'un projet est terminé à moins qu'il n'ait de la documentation, et je l'écris généralement pour des raisons purement égoïstes: afin que je puisse donner aux gens quelque chose à lire au lieu de prendre des appels téléphoniques et des e-mails, ou alors je me souvienne de ce dont nous parlions en dernier mois, ou alors je peux me référer à la façon dont j'ai fait quelque chose si j'ai besoin de le soutenir au milieu de la nuit.
La meilleure façon d'aborder la documentation est de l'écrire COMME VOUS ALLEZ, exactement comme écrire du code de test. C'est incroyable de voir comment quelques modèles pré-écrits (avec en-têtes, talons de code, etc.) peuvent rendre la documentation plus facile et plus rapide à faire. De cette façon, vous pouvez capturer le changement au fur et à mesure qu'il se produit et vous avez moins de terrain à couvrir au fil du temps. Vous êtes plus efficace de cette façon, car vous pouvez consulter la documentation selon vos besoins et la modifier en cours de route. Faire cela dans un wiki, par exemple, facilite les mises à jour, et vous pouvez éviter les problèmes de version de document si la dernière et la meilleure est toujours en ligne au même endroit, et vous pouvez simplement envoyer des liens aux personnes qui ont besoin de la lire.
Si vous passez un peu de temps à documenter, vous travaillerez TOUS plus vite, surtout lorsque quelqu'un de nouveau rejoint l'équipe, car il n'aura pas à passer tout ce temps à tout comprendre. Comprendre des trucs est une partie amusante de nos travaux, mais ce n'est pas amusant quand vous devez le faire rapidement pour réparer la production. Nous gagnerions tous beaucoup de temps si nous écrivions tous quelques notes supplémentaires.
Votre équipe a-t-elle les mêmes problèmes avec les tests ou l'écriture de code de test? Sinon, ce sera une vente plus facile.
Votre documentation est utile à bien des égards:
1) Pour vous, dès maintenant, et pour vos collègues, lorsque vous travaillez sur le projet.
2) À vos clients. Le fait d'avoir des documents (y compris des diagrammes) que vous pouvez montrer aux utilisateurs facilite les discussions lors des réunions, surtout si vous discutez de systèmes complexes. Même si la documentation est incomplète, c'est un point de départ.
3) Aux personnes qui hériteront de votre travail (qui peut même être vous, dans trois ans). Beaucoup de mes plus jeunes collègues pensent qu'ils se souviendront des choses pour toujours. Je sais que je ne m'en souviendrai pas après cette semaine si je ne l'écris pas. Avoir de la documentation vous évite d'avoir à passer une demi-journée à vous souvenir de la façon dont vous avez structuré quelque chose et à devoir tout repenser.
4) À vous et aux autres, si la situation devient politique ou litigieuse. En tant que personne qui prend des notes dans les réunions, pour me tenir éveillé et lutter contre l'ennui, j'ai souvent été le seul à avoir la version écrite d'une décision. La personne qui l'a notée gagne le litige. Rappelez-vous ceci la prochaine fois que quelqu'un dit "Rappelez-vous cette réunion que nous avons eu l'hiver dernier dans la salle de conférence 4, quand nous allions voir X? Fred était là, et qui est ce gars de la comptabilité?"