Un document de conception doit-il contenir une discussion des avantages / inconvénients d'une conception donnée ou doit-il se concentrer sur les faits et la justification?

Je suis actuellement en train de mettre à jour un document de conception afin qu'il soit correct et à jour pour les futurs développeurs.

Actuellement, le document se concentre uniquement sur les faits et présente le design. Il n'y a aucune justification pour les décisions présentées. Je crois qu'il est important de saisir la justification afin que les développeurs sachent pourquoi quelque chose est ainsi, car cela affectera probablement les décisions futures. Il ne m'est pas possible d'ajouter une justification à toutes les décisions de conception, en particulier celles prises avant de commencer à travailler sur le projet, mais je fais ce que je peux dans ce département.

Cependant, certaines des décisions de conception sont, respectueusement, de très mauvaises décisions étant donné les exigences du projet. Mais il y en a aussi de bons.

Ma pensée initiale était que je devrais inclure une discussion sur les problèmes de conception et les solutions ou solutions de contournement potentielles à ces problèmes pour attirer l'attention des futurs responsables, mais je ne suis pas sûr que le document de conception soit un lieu pour ce type de discussion et d'informations. Je ne veux pas qu'une "critique" du design fasse boule de neige pour "en déchirer un nouveau" car d'autres personnes travaillent sur ce système et mettent à jour le document, car cela est clairement inapproprié.

Mon directeur soutiendrait l'une ou l'autre décision, donc c'est à moi de décider. Quelle que soit l'approche que je prends, le document produit serait officiellement versionné et fourni aux développeurs travaillant sur le système, généralement avant qu'ils ne soient chargés de travaux de développement. Il est prévu qu'un nouveau développeur se familiarise avec les documents associés à un système logiciel donné avant de commencer les travaux de développement.

Des questions:

• Un document de conception doit-il s'en tenir aux faits bruts ("c'est la conception") et à la justification ("voici pourquoi c'est la conception") ou doit-il également être utilisé pour signaler des problèmes non défectueux avec la conception qui pourraient être problématiques pour futurs développeurs?
• Si le document de conception ne doit pas être utilisé pour capturer ces informations, quel type de document doit les capturer et quoi d'autre doit être capturé avec une discussion sur les justifications de la conception, les compromis et les problèmes connus (qui ne sont pas des défauts, car les défauts sont suivis en utilisant d'autres outils)?

Si les avantages et les inconvénients peuvent être résumés en une phrase ou deux, alors c'est OK de les mettre dans un document de conception. Tout ce qui est plus long doit être séparé.

Là où je travaille actuellement, il existe généralement un document "Design decicions" distinct pour suivre toutes les décisions importantes et importantes. Souvent formaté avec un paragraphe décrivant le problème (tel que "Certains fichiers doivent être déplacés d'un serveur vers certains utilisateurs à la fin de chaque cycle de traitement, il existe de nombreuses façons de le faire ..."), un tableau avec des colonnes " description de la solution "(comme" déplacer des fichiers via FTP ")," pour "(comme" Facile à gérer pour les utilisateurs ")," contre "(comme" pas suffisamment sécurisé pour la conformité ABC-XYZ ") et une conclusion que explique pourquoi une décision particulière a été choisie (telle que "FTP ne sera pas utilisé car il ne pourra pas répondre à certaines exigences de conformité"). Le document de conception ne fait généralement référence qu'à la décision choisie,

Un document de conception doit-il s'en tenir aux faits bruts ("c'est la conception") et à la justification ("voici pourquoi c'est la conception") ou doit-il également être utilisé pour signaler des problèmes non défectueux avec la conception qui pourraient être problématiques pour futurs développeurs?

Ce n'est pas "soit-ou".

Personne ne lit la documentation en premier lieu. Ils survolent - au mieux. Par conséquent, écrivez le moins de documents possible. Un seul document est tout ce que n'importe qui a de la patience. Il est peu probable qu'un deuxième document "non conçu" contenant "d'autres problèmes" soit lu du tout.

Avantages d'un seul document? Les gens pourraient le lire.

Inconvénients d'un document? Peu. Surtout, il devient obsolète.

Avantages de plusieurs documents? Aucun.

Inconvénients de plusieurs documents? Veuillez lire le principe DRY et la programmation alphabétisée. Plusieurs documents signifient plusieurs sources d'erreurs. Chaque document est en désaccord avec l'autre et en désaccord avec le code. C'est assez évident. C'est le chemin de la folie.

Évitez de vous tordre la main.

Un document pour et contre peut traîner dans des profondeurs indéfinies de discussions de simulation et de nuisances attrayantes.

Si vous estimez qu'il est nécessaire de présenter les avantages et les inconvénients, soyez bref et précis.

Concentrez-vous sur ce qui est.

Gardez ce qui n'est pas jusqu'aux os nus.

Si vous avez effectué des repères, des études ou exploré des alternatives, documentez-les. Mais si vous envisagez simplement des alternatives, minimisez-la.

Cela ne devrait pas être votre histoire personnelle d'épreuves et de tribulations.

• Vous avez eu un problème? Fixé? A pris des semaines? Vraiment du mal? Une anecdote à peine intéressante. C'est fixé dans le code. Les versions précédentes, les versions incorrectes, les versions buggy et les versions à faible performance n'ont pas d'importance. Ce sont des blogueurs au mieux.

• Vous avez toujours un problème? Pas réparé? Cela signifie qu'il existe des alternatives. Documentez cela.

Il y a 3 faits importants dans le processus de prise de décision:

• Ce qui a été essayé et n'a pas fonctionné (et pourquoi cela n'a pas fonctionné, car vous ciblez une cible en mouvement)
• Quel est
• Ce qui pourrait être (en attendant que X soit implémenté ...)

Cependant, à part "Qu'est-ce que c'est", tous les autres confondront le lecteur et l'empêcheront de gâcher le système.

J'aime l'idée de capturer les 2 autres, bien qu'ils soient moins intéressants pour l'apprentissage du système, ils peuvent gagner du temps lors de sa modification.

Par conséquent, je m'appuierais sur l'idée exposée @FrustratedWithFormsDesigner, avec une torsion. Au lieu de créer un autre document, avec un cycle de vie qui lui est propre, je voudrais ajouter une section annexe. Ensuite, pour chaque décision qui mérite d'être discutée, je voudrais signaler l'entrée correspondante dans l'annexe.

Oui. Un document de conception doit expliquer les avantages, les risques et les hypothèses associés à la conception décrite. Un document de conception a plusieurs objectifs:

1. Faites écrire le design pour que tout le monde le comprenne et pour que la compréhension de chacun ne dérive pas avec le temps.

2. Communiquez la conception aux personnes non techniques travaillant sur le projet.

3. Aider à la planification, à l'allocation des ressources, à l'estimation des coûts et à d'autres types de planification.

4. Devient une partie importante de la documentation globale du projet. Lorsque vous rejoignez un projet en cours ou devez en maintenir un qui est terminé, la vie est beaucoup plus facile s'il existe un document de conception bien rédigé.

5. Est souvent l'un des livrables requis par le contrat.

(Il y en a probablement d'autres, mais c'est un bon début.)

Chacun de ces objectifs est bien servi par un doc de conception qui explique clairement pourquoi cette conception a été choisie et quels sont les risques associés:

1. Il est essentiel que tous les membres de l'équipe connaissent les risques et les avantages afin qu'ils puissent travailler ensemble pour éviter ces risques et tirer le meilleur parti des avantages de la conception.

2. Pour les membres non techniques de l'équipe, la compréhension des risques et des avantages est souvent plus importante que les détails de la conception elle-même.

3. La gestion des risques est l'une des choses les plus importantes qu'un chef de projet puisse faire pour assurer le succès, et la première étape consiste à identifier les risques qui doivent être gérés. Il devrait appartenir à un gestionnaire de décider comment gérer les risques, mais il incombe au concepteur de signaler les risques connus de la conception.

4. Même lorsqu'un risque n'est plus un problème, il est souvent utile de le documenter car il peut aider à expliquer la situation au moment de la création du design. Cela peut laisser un responsable décider quelque chose comme: "D'accord, ils l'ont fait de cette façon à l'époque parce que ... mais ce n'est plus un problème, donc je peux remplacer ce code par une implémentation plus simple et plus rapide." Il en va de même pour les avantages, bien sûr.

5. Si vous travaillez sur un projet pour un client, il est particulièrement important de documenter les risques et les avantages. Cela avertit le client que les choses pourraient mal tourner dans certaines circonstances ou que demander des modifications à la conception pourrait compromettre certains des avantages promis.

Je comprends de la question que vous travaillez avec un document de conception existant pour un système qui a déjà été mis en œuvre. Dans ce cas, bon nombre des risques possibles ne sont plus des risques, il n'est donc pas très logique d'essayer de les documenter après coup. Cependant, vous avez maintenant l'avantage du recul, car vous pouvez voir les parties du design original qui n'ont pas si bien fonctionné. Je pense que vous devriez soit: ajouter une section distincte qui identifie les problèmes actuels et propose des solutions (y compris les risques associés!); ou créez un document distinct qui fait la même chose. Cette nouvelle section / document peut évoluer vers le document de conception pour la prochaine version du logiciel.

Voici une entrée de blog sur la rédaction de documents de conception qui peut vous être utile.

S'il y avait des raisons valables d'éviter des solutions plus évidentes ou standard, il convient de les noter. Vous épargnerez beaucoup de problèmes à quelqu'un. Cependant, une technologie particulière peut s'améliorer avec le temps, vos raisons peuvent donc ne pas s'appliquer. Un futur développeur peut alors utiliser son propre jugement.

Je ne sais pas s'il est très utile de signaler tous les défauts. Il peut ne pas être pratique d'apporter les modifications ou d'autres priorités auront lieu. Vous pouvez en corriger certains dans un proche avenir et ce ne sera qu'une chose à mettre à jour.

Personnellement, je ne le mettrais pas dans le document de conception. Un document de conception doit décrire comment il est, pas pourquoi il l'est.

Si vous pensez qu'il y a un bon besoin d'une histoire pour expliquer pourquoi le design est comme ça, peut-être devriez-vous le mettre dans un article wiki (ou dans la base de connaissances que votre entreprise utilise) afin qu'il puisse y avoir un historique de la évolution du design. Les gens peuvent aller le lire, le modifier et ajouter des suggestions. De cette façon, il s'agit plus d'une discussion ouverte que d'un sourcil dans un document.

Je suis d'accord avec vous au sujet de la justification du document de conception.

En tous cas,

dans le processus de mise à jour d'un document de conception écrit par quelqu'un d'autre, je resterais humble et n'essaierais pas de deviner pourquoi une telle décision a été prise.

Donc,

Je voudrais insérer une justification uniquement sur les modifications apportées à la conception pendant la maintenance.