Déterminer la bonne quantité de documentation

Là où je travaille actuellement, l'approche générale est -

éviter autant que possible la documentation

Documenter uniquement si une autre équipe en a besoin

juste pour clarification, je ne parle pas de documentation de code - ce que nous faisons, je veux dire toute la documentation entourant le processus de conception - si c'est des schémas UML ou DB, des diagrammes de classes et des documents Word avec des spécifications et autres.

Je vais énumérer la raison pour laquelle mon patron n'a pas documenté:

1. cela prend du temps - se concentrer sur la mise en œuvre
2. si la conception change - alors la documentation devrait changer, double problème
3. en fin de compte, vous obtenez juste des centaines de pages que personne ne veut lire, et personne ne modifie vraiment, donc avec le temps cela deviendra obsolète
4. C'est une douleur - personne ne veut vraiment le faire

Maintenant, je me rends compte que nous travaillons plus rapidement, mais je me souviens aussi du temps passé ici et plongé directement dans un vieux code, sans rien comprendre.

En fait, je n'obtiens toujours pas la plupart de cet ancien code, et parfois quand j'entre, je vois de nombreux correctifs de différents développeurs essayant de faire de petits ajustements.

Je pense vraiment que le manque de documentation favorise ce type de correctifs et le manque de compréhension du système au sens large.

Ma question est:

Comment équilibrer la documentation afin de promouvoir une connaissance continue au sein de l'équipe tout en étant rapide et efficace?

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é?"

Chez mes derniers employeurs, nous avons eu un wiki "développement". D'importants morceaux de fonctionnalités (nouveau flux d'import / export, comment fonctionne le sous-système de sécurité, où le système stocke les documents téléchargés, etc.) sont-ils tous documentés là-bas. Il s'agit généralement d'un élément obligatoire à compléter avant l'étape de révision du code. Il y a généralement un peu de résistance au début, mais une fois que quelqu'un doit aller chercher un peu d'informations et qu'elles sont là, vous avez un autre converti.

La bonne chose à propos de l'avoir dans un format wiki est que vous êtes beaucoup moins enclin à faire tout le joli formatage Word et autres et à simplement écrire les vraies informations que vous devez enregistrer. La plupart (sinon tous) des packages wiki vous permettront de télécharger des documents ou des images (comme des diagrammes UML Visio ou des wireframes d'interface utilisateur), de sorte que vous puissiez également avoir des éléments visuels.

Comme la plupart des choses, je pense que vous devriez viser à faire le minimum qui pourrait éventuellement fonctionner. Ce n'est pas la même chose que rien cependant.

Vous ne pouvez pas échapper à l'allocation de temps pour écrire la documentation appropriée. Équilibrez-le comme vous le souhaitez en fonction de la quantité de travail qui vous est confiée, mais laissez un bon 15-20% de votre temps pour documenter ce que vous avez fait. Tout le monde dans l'équipe doit être à bord avec cela, y compris votre manager, sinon vous ne documenterez que pour le bénéfice des autres et vous n'aurez rien en retour. La documentation doit faire partie intégrante de votre processus de développement.

La documentation devrait vous dire POURQUOI vous avez fait quelque chose pendant que vous laissez la partie COMMENT au code réel et QUELLE partie aux tests unitaires. Rien de plus est une douleur. C'est généralement assez bon pour les personnes intelligentes qui veulent juste un point de départ.

N'oubliez pas non plus de maintenir une architecture globale de haut niveau pour chaque gros composant de votre base de code. Il est très facile d'incorporer de nouveaux membres de l'équipe.

Enfin, chaque fois que vous ajoutez un correctif farfelu, un lien vers votre base de données de bogues à partir d'un commentaire - très utile.

Votre patron a raison de ne pas imprimer de documentation UML que personne ne lira. Ce que nous faisons dans notre équipe est de naviguer en direct dans le modèle en utilisant des vues de diagramme de classe. Le principe est de toujours mettre à jour MOF, le modèle UML en direct à partir du code et de laisser le diagramme de classes être uniquement une visionneuse du modèle mais pas le modèle lui-même.

Cela fonctionne très bien car toute la complexité se fait en backoffice au niveau du modèle. Je peux refactoriser mon projet, écrire de la documentation java ou écrire de la documentation uml dans le modèle. C'est une sorte de click and go. Lorsque vous cliquez sur, vous obtenez la documentation en direct. Si quelque chose n'est pas clair, j'ouvre le diagramme de classe et commence à jouer avec. Supprimer des classificateurs de diagramme, ajouter de nouveaux classificateurs, zoomer et dézoomer, afficher l'association, supprimer l'association, etc. Le modèle n'est pas modifié car je ne crée pas de nouvelles informations sur le modèle, je les utilise simplement.

Il est vraiment important d'ouvrir le diagramme d'un paquet et de pouvoir lire directement dans le diagramme de classe un commentaire sur ce que cette classe est censée être. Qu'est-ce que cette méthode est censée faire et quel est le flux, etc.

UML est génial, vraiment utile, mais nous devrions cesser d'utiliser le développement piloté par modèle afin de donner plus de flexibilité et plus d'itération aux étapes de modélisation / développement. Le diagramme de classe est mis à jour en direct à partir du code et la documentation est toujours précise et disponible en un seul clic. Je ne mentionnerai pas un outil mais si vous utilisez Java et Eclipse, il est facile de trouver quel outil j'utilise :-)