Quel est un moyen efficace d'enregistrer les justifications des décisions de conception de produits?

Dans notre entreprise, nous n'utilisons aucun document de conception de produit. Nous avons trois employés au total, donc toutes les discussions sur la conception de produits se déroulent en personne ou sur Slack. (Nous sommes également sur le package de base Slack qui permet uniquement d'afficher les messages les plus récents.)

Notre produit en est encore à ses débuts et nous revoyons souvent des éléments de conception décidés il y a des mois.

Un problème auquel nous sommes confrontés de manière désespérément fréquente est d'oublier pourquoi une décision de conception de produit a été prise. Il en résulte des heures perdues à rechaper le même terrain.

Comment enregistrer efficacement les justifications des décisions de conception?

Notre flux de travail est basé sur Pivotal Tracker. Une solution qui m'est venue consiste à enregistrer les justifications de toutes les décisions de conception pertinentes en tant que commentaires sur la user story elle-même, mais cela semble peu fiable.

Pour être clair à 100%: je ne parle pas de la conception du code. Je parle de la conception du produit qui est réalisée par le code. En d'autres termes, je ne parle pas de décisions comme "devrions-nous structurer cette classe en utilisant la composition plutôt que l'héritage multiple?"; Je parle de décisions telles que "devons-nous demander à un utilisateur de confirmer son adresse e-mail avant de pouvoir se connecter?".

Le but de la documentation est de permettre à l'entreprise d'afficher un enregistrement des raisons pour lesquelles des décisions ont été prises, pour aider à prendre d'autres décisions sur les mêmes sujets.

Vous enregistrez les justifications des décisions de conception en les notant. Idéalement à proximité de l'article qui fait l'objet de la décision (qui n'est pas une «user story» - les user stories sont des descriptions de ce qui doit être mis en œuvre, pas comment).

C'est surtout pour cela que les commentaires sont faits - pour enregistrer pourquoi un morceau de code ou une structure spécifique ressemble à cela (et je ne parle pas exclusivement de commentaires de code). Si le sujet de votre conception est une fonction, faites un commentaire d'introduction à la fonction. S'il s'agit d'un cours, faites un commentaire au début du cours sur la justification. Si vous avez un groupe de classes qui devraient toutes suivre la même structure, ajoutez un document de conception distinct (comme un fichier "readme") au package contenant ces classes. Si l'objet de votre conception est un diagramme UML, ajoutez des commentaires à la section de description du diagramme.

Les documents de conception à mon humble avis peuvent avoir leur valeur, mais s'ils décrivent des choses trop "loin" de l'élément qu'ils décrivent, ils ont tendance à devenir très rapidement incohérents. Ma recommandation est donc de mettre toute documentation de conception aussi près que possible de l'article conçu.

Utilisez des documents séparés uniquement lorsque vous souhaitez documenter des décisions de conception qui affectent de nombreux endroits différents de votre code de manière transversale. Lorsque vous les utilisez, essayez de les intégrer à votre base de code et placez-les au niveau de la hiérarchie correspondante du sujet conçu (donc si vous décidez de la conception d'un module composé de plusieurs fichiers de code source, placez la description de la conception " à l'intérieur "de ce module, mais pas dans un fichier de classe, pas sur une" description de haut niveau "qui est valide pour les autres modules, et certainement pas dans un wiki séparé en dehors de votre SCCS. Si vous voulez enregistrer un produit" de haut niveau ", décisions de conception larges, puis un document de haut niveau peut-être le meilleur endroit, mais assurez-vous que ce document reste à ce niveau d'abstraction.

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!

Je suggère de configurer une instance privée de MediaWiki ou un logiciel wiki similaire. Il est vraiment facile d'organiser et de réorganiser le contenu là-bas, et vous pouvez copier et coller de nouvelles discussions directement dans l'onglet de discussion des articles wiki pertinents. Nous avons utilisé MediaWiki lors de mon dernier travail pour l'ensemble de nos documents d'architecture et d'API, et ce fut une bouée de sauvetage.

Pensez-y du point de vue du codeur qui va devoir le changer dans 12 mois.

Si vous ajoutez cette règle métier en tant que test automatisé, le changement sera effectué ET ALORS vous obtiendrez du test échoué l'exigence contradictoire (et j'espère que vous capturez la personne associée à l'exigence d'origine et la raison pour laquelle elle est spécifiée).

Je considère que le document de conception (l'endroit où vous mettez vos diagrammes BPMN, diagrammes de transaction, même une photo du tableau blanc, etc.) est similaire au code, juste une forme non exécutable ... ce qui signifie ce que vous essayez de faire l'enregistrement s'apparente à un commentaire de code, mais une exigence (testable) spécifiée à l'avance dans la conception. Vraisemblablement, si vous êtes une boutique agile et que vous concevez toujours votre code, vous le faites juste à la dernière minute avant de l'écrire. Conservez-le dans la base de code avec tous les autres documents de projet.

Quoi que vous fassiez, assurez-vous qu'il est stocké de manière consultable (par exemple, vous souhaiterez peut-être afficher toutes les règles métier liées à l '"authentification" lors de la spécification de nouvelles modifications).

Comme toujours lorsque vous écrivez quelque chose, vous devez vous demander qui est le public visé. Je crois fermement que les documents de conception sont là pour mes pairs développeurs, actuels ou futurs. Le document les aide à comprendre ce que je construis ou ce qui a été construit (aperçu de haut niveau) et, plus important encore, pourquoi. C'est un endroit pour documenter les alternatives que vous avez envisagées, les avantages et les inconvénients de chacune.

Dire qu'il est acceptable qu'une conception vive dans le cerveau des gens laisse de côté que les développeurs avancent et trouvent différents emplois, emportant avec eux ces informations précieuses.

Avoir votre code comme seule documentation de conception, c'est comme trouver votre chemin en ville à l'aide d'une loupe. Une carte est tellement plus utile (malheureusement, il n'y a pas d'équivalent GPS pour le code source).

Je suis d'accord que la documentation de conception pourrit encore plus vite que le code. Et comme il n'y a pas de validation possible entre les deux, la seule chose que vous pouvez faire est de les rapprocher. OMI, un document de conception daté fournit toujours des informations précieuses.