Quel est un moyen efficace d'enregistrer des raisons sur les décisions de conception des produits?
Chez notre société, nous n'utilisons aucun document de conception de produits. Nous avons trois employés pour que toutes les discussions sur la conception du produit se produisent en personne ou sur le mou. (Nous sommes également sur le paquet de base qui permet uniquement de visualiser les messages les plus récents.)
Notre produit est toujours à ses débuts et nous revisitons souvent des éléments de conception qui ont été décidés il y a des mois.
Un problème que nous sommes confrontés à une base pénible est en train d'oublier pourquoi une décision de conception du produit a été prise. Cela se traduit par des heures gaspillées rechate le même terrain.
Comment pouvons-nous enregistrer efficacement les raisons des décisions de conception?
Notre flux de travail est basé sur Pivotal Tracker. Une solution qui me survient est d'enregistrer les raisons pour toutes les décisions de conception pertinentes comme des commentaires sur l'histoire de l'utilisateur lui-même, mais cela semble peu fiable.
Être 100% clair: je ne parle pas de la conception du code. Je parle de la conception du produit réalisé par le code. En d'autres termes, je ne parle pas de décisions comme "Devrions-nous structurer cette classe à l'aide de la composition plutôt que de multiples héritages?"; Je parle de décisions comme "si nous avons besoin d'un utilisateur de confirmer leur adresse e-mail avant de pouvoir se connecter?".
Le but de la documentation est de permettre à l'entreprise de considérer les raisons pour lesquelles des décisions ont été prises pour aider à prendre des décisions supplémentaires sur les mêmes sujets.
Vous enregistrez des raisons de décisions de conception en les écrivant. Idéalement à proximité de l'article qui est soumis à la décision (qui n'est pas une "histoire d'utilisation" - les histoires d'utilisateurs sont des descriptions ce qui doit être mis en œuvre, pas comment).
C'est surtout ce que commentaires sont faits pour - à enregistrer pourquoi Un morceau de code ou de structure spécifique semble être (et je ne parle pas exclusivement des commentaires du code). Si le sujet de votre conception est une fonction, faites un commentaire d'introduction à la fonction. Si c'est une classe, faites un commentaire au début d'une classe sur la justification. Si vous avez un tas de classes qui devraient tous suivre la même structure, ajoutez un document de conception distinct (comme un fichier "README") à l'emballage contenant ces classes. Si le sujet de votre conception est un diagramme UML, ajoutez des commentaires à la section Description du diagramme.
Les documents de conception de l'OMHO peuvent avoir leur valeur, mais s'ils décrivent des choses aussi "loin" de l'article qu'ils décrivent, ils ont tendance à devenir incohérents très rapidement. Donc, ma recommandation est de mettre toute documentation de conception aussi proche que possible de l'élément conçu.
Utilisez des documents distincts uniquement lorsque vous souhaitez documenter les 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 faire partie de votre base de code et de les placer au niveau de la hiérarchie correspondant du sujet conçu (donc si vous prenez une décision de conception pour un module consiste en plusieurs fichiers de code source, placez la description de la conception ". Inside "Ce module, mais pas dans un fichier de classe, pas sur une" description de haut niveau "valide pour d'autres modules, et ne sont certainement pas dans un wiki séparé en dehors de votre SCCS. Si vous souhaitez enregistrer un" haut niveau ", produit Des décisions de conception larges, puis un document de niveau supérieur peut-être le meilleur endroit, mais assurez-vous que ce document reste sur ce niveau d'abstraction.
Considérer une approche agile. Je veux dire, si vous avez les ressources temporelles et d'excellentes compétences en écriture pour écrire toutes les décisions de conception, vous faites des gars avec leurs rationalisations, il suffit de documenter tout. Réalisticument, je suppose que vous n'êtes pas dans une telle position. ne approche agile peut aider à un défi majeur pour la documentation des raisons: vous ne savez souvent pas quelles rationalisations étaient les plus importantes jusqu'à ce que plus tard.
Approchons le problème d'un point de vue holistique. Vous avez des raisons pour votre décision. Ils sont piégés à Squishyware en ce moment, le cerveau de l'équipe. Malgré le montant de la documentation de crédit obtient, stocker des raisons dans Squishyware n'est pas si mauvaise. Nous sommes en fait vraiment Bien comme une espèce à se souvenir des choses importantes. C'est pourquoi toutes les grandes entreprises ont une "connaissance tribale", même lorsque ces sociétés cherchent à documenter toute cette connaissance tribale.
Maintenant, vous avez un problème. Vous constatez que le sqiushyware ne tient pas assez bien les rationalisations. Bon pour vous pour réaliser qu'il y a un problème et identifier qu'il doit être résolu! Ce n'est pas toujours une étape facile! Nous sommes donc à peu près sûr que la solution est de décharger une partie de cette justification dans la documentation. Cependant, ça ne suffit pas. Nous ne pouvons jamais oublier la seconde moitié du puzzle, qui rechargeons la justification de la justification dans le spectateurs lorsque vous devez prendre une décision. J'ai vu de nombreuses équipes qui documentent tout comme un fou, mais le contenu n'est pas réellement organisé pour aider à prendre de bonnes décisions, alors ils finissent par oublier des raisons même s'ils sont écrits.
Donc, vous avez un processus en deux étapes. Vous devez obtenir la raison de sortir de l'écurie et dans la documentation. Ensuite, vous devez vous assurer que la documentation est assez bien organisée pour ramener le retour rationnel dans Squishyware lorsque vous en avez besoin! Maintenant, je pense que nous avons assez d'une déclaration de problème pour réaliser où les défis aimeront. Lorsque vous documez-vous, vous ne savez généralement pas qui va le regarder plus tard, ou ce qu'ils cherchent. De même, lorsque vous regardez la documentation, vous ne savez généralement pas ce que vous recherchez (au mieux, vous savez peut-être quand).
Donc, une grande entreprise peut essayer de gérer cela dans deux grands blocs. D'abord, ils peuvent aller développer des exigences en fonction de ce que les gens ont besoin lors de la recherche de la documentation. Ensuite, ils utilisent ces exigences pour créer un processus de développement de ladite documentation. Et, si j'ose le dire, tout le monde se plaint, car presque personne ne sait Exactement Quelle documentation devrait ressembler au premier jour. La documentation est toujours incomplète et les développeurs se plaignent toujours que le processus est trop lourd.
Il est temps d'aller agile.
Mon conseil serait de démarrer un effort agile pour améliorer votre processus de documentation: les neuf mètres de gastrywyware à documenter et à revenir à Squishyware. Reconnaître devant le front que vous perdrez des informations car votre processus n'est pas parfait, mais ça va parce que vous essayez toujours de comprendre le processus! Vous manqueriez plus si vous essayez de créer une taille unique pour toutes les solutions.
Quelques nordbations particulières que je regarderais: * explorez la documentation informelle. La documentation formelle est excellente, mais son temps prend beaucoup de temps. L'une des objectifs de la documentation consiste à libérer des informations provenant du développeur squishywayware et de la mettre sur papier. La documentation informelle maintient le coût de le faire au minimum.
- accepter des formats de documentation non fiables. Rien ne sera correct la première fois. Il est préférable d'obtenir les données et de déterminer comment le rendre fiable plus tard. Par exemple, vous pouvez documenter vos raisons dans un bloc <logiciel> </ Justification> ou quelque chose de similaire, ce qui faciliterait la récolte de ces données plus tard. Stocker les rationalisations dans une histoire d'utilisateur, pour l'instant, c'est bien!
- N'oubliez jamais la valeur de l'organisation. Découvrez comment vous, en équipe, aime rechercher des raisons de recherche dans la documentation et essayez de le documenter. Chaque équipe aura un processus différent. Sur l'une de mes équipes, nous ne pourrions jamais trouver le billet qui avait la justification de la justification immédiate. Ce que nous pouvions faire est de trouver une ligne de code qui comptait, faites un
svn blamePour savoir quand il a changé et pourquoi, puis allez regarder les billets. Une fois que nous étions là-bas, nous mettons généralement toutes les raisons de la justification dont nous avions eu raison sur le billet. Cela vient de travailler pour nous, découvrez ce qui fonctionne pour vous. - La documentation organique peut augmenter au fil du temps. Il est rare que les développeurs sachent quelles rationnelles sont les plus importantes le jour où ils devaient l'écrire. Nous découvrons généralement lesquels étaient importants plus tard. Si vous avez un processus de toilettage pour la documentation permettant aux développeurs de gérer leur propre petit jardin de raisons, les importants augmenteront à la surface. Encore plus important, des raisons pourraient changer. Vous pouvez vous rendre compte que deux changements différents, avec deux rationnelles différentes, ont été vraiment mieux décrites par une seule justification qui fonctionne pour les deux. Maintenant, il y a moins de contenu entre vous et les décisions!
Pensez-y du point de vue du codeur qui va être invité à le changer dans 12 mois.
Si vous ajoutez cette règle d'entreprise sous forme de test automatisé, le changement sera effectué, puis vous obtiendrez du test de défaillance de l'exigence contradictoire (et j'espère que vous capturez la personne associée à l'exigence d'origine et à leur motif de la spécifier).
Je considère le document de design (l'endroit où vous mettez vos diagrammes de BPMN, des diagrammes de transaction, même une photo du tableau blanc, etc.) comme étant similaire au code, juste une forme non exécutable ... ce qui signifie ce que vous essayez de L'enregistrement s'apparente à un commentaire de code, mais d'une exigence (testable) spécifiée à l'avant dans la conception. Vraisemblablement si vous êtes un magasin agile, vous concevez toujours votre code, vous venez de le faire à la dernière minute avant de l'écrire. Gardez ceci 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 interrogeable (par exemple, vous souhaiterez peut-être extraire toutes les règles d'entreprise liées à "Authentification" lors de la spécification de nouveaux changements).
Je suggérerais de mettre en place une instance privée de MediaWiki ou de certains logiciels de wiki similaires. Il est vraiment facile d'organiser et de réorganiser le contenu, et vous pourriez copier et coller de nouvelles discussions directement dans l'onglet Discussion de l'article (s) Wiki (s) concerné (s). Nous avons utilisé Mediawiki à mon dernier emploi pour toutes nos documents d'architecture et d'API, et c'était une vie de sauvetage.
Comme toujours lorsque vous écrivez quelque chose, vous devez vous demander qui est l'audience prévue. Je crois fermement que les documents de conception sont là pour mes développeurs de pairs, ceux actuels ou futurs. Le document les aide à comprendre ce que je construit 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 considérées, les avantages et les inconvénients de chacun.
En disant que tout va bien pour que certains concevoirs vivent dans les cerveaux des gens laisse pour que les développeurs avancent et trouvent différents emplois, en prenant avec eux que des informations précieuses.
Avoir votre code soit la seule documentation de conception, c'est comme trouver votre chemin autour de la 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 va encore plus rapidement que le code. Et comme il n'y a pas de validation possible entre les deux, la seule chose que vous puissiez faire est de les garder proches. IMO, un document de conception daté fournit toujours des informations précieuses.