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

30

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.

henrebotha
la source
13
Si vous sentez que vous avez besoin d'un formulaire de conception, pourquoi ne pas simplement créer un document de conception?
MetaFight
Je suppose que les justifications seront enregistrées en prose, prose écrite à première vue. À qui s'adresse ce lecteur?
Laurent LA RIZZA
Pourquoi dites-vous que l'enregistrement de cela sur les user stories sur Pivotal semble peu fiable? Je n'ai jamais utilisé ce logiciel, mais normalement un ticket est un bon endroit pour enregistrer la motivation pour augmenter le ticket. Ne vous contentez pas de saisir "Obliger l'utilisateur à confirmer l'adresse e-mail", entrez "Obliger l'utilisateur à confirmer l'adresse e-mail. Cela aide parce que ..." Êtes-vous en train de dire que ce n'est pas fiable parce que vous pourriez ne pas vous embêter à le faire (c'est-à-dire que vous voulez un processus qui force vous de faire la bonne chose), ou peu fiable parce que les vieilles histoires de Pivotal disparaissent dans un trou noir et que vous ne les trouverez pas, ou y a-t-il un autre problème?
Steve Jessop
Qui sont les auteurs et qui sont les consommateurs de cette documentation? Il me semble que "l'entreprise" est l'auteur et que tout le monde en est le lecteur? Serait-ce exact? (Je comprends que vous êtes petit en ce moment, mais si vous deviez grandir, quelles seraient les réponses?)
mlk
Je suggérerais "devrions-nous demander à un utilisateur de confirmer son adresse e-mail avant de pouvoir se connecter?" le type de décisions devrait être soumis à des critères d'acceptation.
kumards

Réponses:

26

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.

Doc Brown
la source
Concernant les commentaires: ne diriez-vous pas que le but des commentaires est de décrire le code? Parce que le genre de problème dont je parle est des problèmes de conception, comme: l'utilisateur doit-il avoir des autorisations X compte tenu des paramètres de compte Y? Le but du code est de permettre la conception, donc je ne pense pas que l'endroit approprié pour discuter de la conception soit dans le code.
henrebotha
5
@henrebotha: Vous semblez avoir une idée différente de moi sur ce qu'est le design, peut être ou devrait être. Le code, c'est le design. La structure du code est la conception. La structure des interfaces utilisateur est la conception. Les méta structures de code ou de classes sont de conception. Une question comme "si l'utilisateur a des autorisations X compte tenu des paramètres du compte Y" me semble être quelque chose que vous ne voulez pas câbler n'importe où dans votre logiciel - ressemble plus à une exigence configurable. La façon dont vous implémentez cette exigence dans le code peut être une décision de conception, vous pouvez donc la commenter quelque part dans votre code.
Doc Brown
2
@henrebotha: si vous câblez les autorisations X aux paramètres de compte Y, le code sera affecté par cette décision. Du code qui contrôle les autorisations, du code qui gère les paramètres du compte, du code d'interface utilisateur, du code de contrôleur. Il devrait donc y avoir un commentaire dans le code à tous ces endroits. Bien sûr, pour éviter les répétitions, tous les commentaires peuvent faire référence à un document de conception distinct, s'il y a une raison derrière cela qui affecte de nombreux endroits différents (comme je l'ai dit dans ma réponse) ..
Doc Brown
1
Je ne conteste pas que les décisions de conception affectent le code. Bien sûr, les décisions de conception affectent le code. Cela ne signifie toujours pas que les commentaires sont le bon endroit pour enregistrer les décisions de conception de produits.
henrebotha
1
@henrebotha: cela dépend de ce que vous entendez par "décisions de conception de produits". Les décisions de conception «à l'échelle du produit» peuvent appartenir à un document au «niveau supérieur» de la documentation de votre produit. Si vous entendez tout type de "décisions de conception à l'intérieur de votre produit", certains d'entre eux appartiennent aux commentaires de code, d'autres non. Mais je ne parle pas seulement des commentaires de code, voir ma modification. Je parle de toute forme de commentaires (à l'intérieur du code ou dans des documents séparés) que vous faites partie de votre base de code.
Doc Brown
8

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!
Cort Ammon - Rétablir Monica
la source
0

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.

zerobandwidth
la source
2
Architecture et décisions de haut niveau - ça pourrait aller. Documents API - NON! Certaines personnes de notre organisation ont essayé cela dans le passé et c'est toujours la même chose - les documents de bas niveau ne sont plus synchronisés avec le code. Les wikis n'interagissent pas bien avec le VCS, les gens oublient ou ne prennent pas le temps de le mettre à jour, etc. Les documents d'API appartiennent au code , devant les fonctions qu'ils décrivent. Si vous sentez que vous en avez besoin dans votre intranet, utilisez un générateur HTML comme doxygen pour les extraire de là. Mais faites-vous plaisir et ne les conservez pas séparément, manuellement, dans un wiki.
Doc Brown
3
Je suis fermement convaincu que toutes les justifications de conception doivent être écrites dans le référentiel de code source. Tout autre endroit, et non seulement ils se désynchronisent, mais ils ne se souviendront pas non plus de leur histoire.
cmaster
Dévoter une solution qui fonctionne ... Wow. Alors ok.
zerobandwidth
0

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).

Michael
la source
0

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.

MvdD
la source