Envisagez une approche agile. Je veux dire, si vous avez les ressources de temps et d'excellentes compétences en écriture pour écrire chaque décision de conception que vous prenez avec leurs justifications, documentez tout. De façon réaliste, je suppose que vous n'êtes pas dans une telle position. Une approche agile peut aider à relever un défi majeur pour la documentation des justifications: vous ne savez souvent pas quelles raisons étaient les plus importantes jusqu'à plus tard.
Abordons le problème d'un point de vue holistique. Vous avez des raisons pour votre décision. Ils sont piégés dans un squishyware en ce moment, le cerveau de l'équipe. Malgré la quantité de documentation de crédit obtenue, le stockage des justifications dans sqishyware n'est pas si mal. En fait, nous sommes vraiment bons en tant qu'espèce pour nous souvenir des choses importantes. C'est pourquoi chaque grande entreprise possède des «connaissances tribales», même lorsque ces sociétés cherchent à documenter toutes ces connaissances tribales.
Vous avez maintenant un problème. Vous constatez que le sqiushyware ne tient pas suffisamment les logiques. Bon pour vous d'avoir réalisé qu'il y a un problème et d'avoir identifié qu'il doit être résolu! Ce n'est pas toujours une étape facile! Nous sommes donc presque sûrs que la solution consiste à décharger une partie de cette justification dans la documentation. Mais cela ne suffit pas. Nous ne pouvons jamais oublier la seconde moitié du puzzle, qui consiste à recharger la justification dans le squishyware lorsque vous devez prendre une décision. J'ai vu beaucoup d'équipes qui documentent tout comme un fou, mais le contenu n'est pas réellement organisé pour aider à prendre de bonnes décisions, alors elles finissent par oublier les justifications même si elles sont écrites .
Vous avez donc un processus en deux étapes. Vous devez obtenir la justification du squishyware et dans la documentation. Ensuite, vous devez vous assurer que la documentation est suffisamment bien organisée pour ramener le rationnel dans le squishyware lorsque vous en avez besoin! Maintenant, je pense que nous avons assez d'un énoncé de problème pour réaliser où les défis vont plaire. Lorsque vous documentez, vous ne savez généralement pas qui va les consulter plus tard, ni ce qu'ils recherchent. De même, lorsque vous examinez la documentation, vous ne savez généralement pas ce que vous recherchez (au mieux, vous savez peut-être quand).
Une grande entreprise peut donc essayer de gérer cela en deux gros blocs. Tout d'abord, ils peuvent développer des exigences en fonction de ce dont les gens ont besoin lorsqu'ils recherchent la documentation. Ensuite, ils utilisent ces exigences pour construire un processus de développement de ladite documentation. Et, si j'ose le dire, alors tout le monde se plaint parce que presque personne ne sait exactement à quoi devrait ressembler la documentation le premier jour. La documentation est toujours incomplète et les développeurs se plaignent toujours que le processus est trop lourd.
Il est temps de devenir agile.
Mon conseil serait de lancer un effort agile pour améliorer votre processus de documentation: les neuf mètres entiers de squishyware à documenter et revenir à squishyware. Reconnaissez d'avance que vous allez perdre des informations parce que votre processus n'est pas parfait, mais c'est bien parce que vous essayez toujours de comprendre le processus! Vous en manqueriez plus si vous essayiez de créer une solution universelle.
Quelques morceaux particuliers que je regarderais: * Explorez la documentation informelle. La documentation officielle est excellente, mais elle prend du temps. L'un des objectifs de la documentation est de publier les informations du développeur squishyware et de les mettre sur papier. Une documentation informelle réduit au minimum le coût de cette opération.
- Acceptez les formats de documentation non fiables. Rien ne se passera bien la première fois. Il est préférable d'obtenir les données et de déterminer comment les rendre fiables ultérieurement. Par exemple, vous pouvez documenter vos justifications dans un bloc <rationale> </rationale> ou quelque chose de similaire, ce qui faciliterait la collecte de ces données plus tard. Pour l'instant, stocker les justifications dans une user story est très bien!
- N'oubliez jamais la valeur de l'organisation. Découvrez comment vous, en équipe, aimez rechercher des justifications dans la documentation et essayez de documenter cela. Chaque équipe aura un processus différent. Dans l'une de mes équipes, nous n'avons jamais pu trouver le ticket qui avait la raison d'être dessus tout de suite. Ce que nous pourrions faire, c'est trouver une ligne de code qui comptait, faire une
svn blamerecherche pour savoir quand elle a changé et pourquoi, puis aller voir les tickets. Une fois que nous y étions, nous avons généralement mis toutes les justifications dont nous avions besoin sur le ticket. Cela vient de fonctionner pour nous, découvrez ce qui fonctionne pour vous.
- La documentation organique peut évoluer avec le temps. Il est rare que les développeurs sachent quelles justifications sont les plus importantes le jour où elles ont besoin de l'écrire. Nous découvrons généralement lesquels étaient importants par la suite. Si vous avez un processus de préparation de la documentation qui permet aux développeurs de gérer leur propre petit jardin de justifications, les plus importantes remonteront à la surface. Plus important encore, les justifications peuvent changer. Vous pouvez vous rendre compte que deux changements différents, avec deux justifications différentes, étaient vraiment mieux décrits par une seule justification qui fonctionne pour les deux. Maintenant, il y a moins de contenu entre vous et les décisions!