par Angela Zhang
En tant qu’ingénieur logiciel, je passe beaucoup de temps à lire et écrire des documents de conception. Après avoir parcouru des centaines de ces documents, j’ai vu de première main une forte corrélation entre de bons documents de conception et le succès final du projet.
Cet article est ma tentative de décrire ce qui rend un document de conception génial.,
L’article est divisé en 4 sections:
- Pourquoi écrire un document de conception,
- les éléments à inclure dans un document de conception,
- Comment l’écrire
- Le processus autour d’elle
Pourquoi écrire un document de conception?
Un document de conception — également connu sous le nom de spécification technique — est une description de la façon dont vous prévoyez de résoudre un problème.
Il y a déjà beaucoup d’écrits sur les raisons pour lesquelles il est important d’écrire un document de conception avant de plonger dans le codage. Donc, tout ce que je vais dire ici est:
Un document de conception est l’outil le plus utile pour s’assurer que le bon travail est fait.,
L’objectif principal d’un document de conception est de vous rendre plus efficace en vous forçant à réfléchir à la conception et à recueillir les commentaires des autres. Les gens pensent souvent que le but d’un document de conception est d’enseigner aux autres sur un système ou de servir de documentation plus tard. Bien que ceux-ci puissent être des effets secondaires bénéfiques, ils ne sont pas le but en soi.
Comme une règle générale, si vous travaillez sur un projet qui peut prendre 1 ingénieur mois ou plus, vous devez écrire un doc. Mais ne vous arrêtez pas là — beaucoup de petits projets pourraient également bénéficier d’un mini design doc.
Super!, Si vous lisez encore, vous croyez en l’importance des documents de conception. Cependant, différentes équipes d’ingénierie, et même des ingénieurs au sein d’une même équipe, écrivent souvent des documents de conception très différemment. Parlons donc du contenu, du style et du processus d’un bon document de conception.
Que faut-il inclure dans un document de conception?
Un document de conception décrit la solution à un problème. Étant donné que la nature de chaque problème est différente, vous voudrez naturellement structurer votre document de conception différemment.,
Pour commencer, voici une liste de sections que vous devriez au moins envisager d’inclure dans votre prochain document de conception:
Title and People
Le titre de votre document de conception, le(s) auteur (s) (devraient être les mêmes que la liste des personnes qui envisagent de travailler sur ce projet), le (s) réviseur (s) du document (nous en parlerons plus en détail dans la section Processus ci-dessous), et la date de la dernière mise à jour de ce document.
Aperçu
Un résumé de haut niveau que chaque ingénieur de l’entreprise doit comprendre et utiliser pour décider s’il leur est utile de lire le reste du document., Il devrait être 3 paragraphes max.
Contexte
Une description du problème en question, pourquoi ce projet est nécessaire, ce que les gens doivent savoir pour évaluer ce projet et comment il s’inscrit dans la stratégie technique, la stratégie produit ou les objectifs trimestriels de l’équipe.,
Objectifs et non-objectifs
La section Objectifs devrait:
- décrivez l’impact utilisateur de votre projet-où votre utilisateur pourrait être une autre équipe d’ingénierie ou même un autre système technique
- spécifiez comment mesurer le succès à l’aide de métriques — points bonus si vous pouvez créer un lien vers un tableau de bord qui suit ces métriques
Les non — objectifs sont tout aussi importants pour décrire les problèmes que vous ne corrigerez pas afin que tout le monde soit sur la même page.,
Jalons
Une liste de points de contrôle mesurables, afin que votre PM et le gestionnaire de votre gestionnaire puissent la parcourir et savoir à peu près quand différentes parties du projet seront réalisées. Je vous encourage à décomposer le projet en étapes majeures pour l’utilisateur si le projet dure plus d’un mois.
Utilisez les dates du calendrier afin de prendre en compte les retards non liés, les vacances, les réunions, etc., Il devrait ressembler à quelque chose comme ceci:
Start Date: June 7, 2018Milestone 1 — New system MVP running in dark-mode: June 28, 2018Milestone 2 - Retire old system: July 4th, 2018End Date: Add feature X, Y, Z to new system: July 14th, 2018
Ajouter un paragraphe ici si l’ETA de certains de ces jalon changements, afin que les intervenants puissent facilement voir les plus up-to-date des estimations.
Solution existante
En plus de décrire l’implémentation actuelle, vous devez également parcourir un exemple de flux de haut niveau pour illustrer comment les utilisateurs interagissent avec ce système et / ou comment les données le traversent.,
Une histoire utilisateur est un excellent moyen de cadrer cela. Gardez à l’esprit que votre système peut avoir différents types d’utilisateurs avec différents cas d’utilisation.
Solution Proposée
Certaines personnes appellent cela la Technique, section Architecture. Encore une fois, essayez de parcourir une histoire d’utilisateur pour concrétiser cela. N’hésitez pas à inclure de nombreuses sous-sections et diagrammes.
Fournissez d’abord une grande image, puis remplissez beaucoup de détails. Visez un monde où vous pouvez écrire ceci, puis prendre des vacances sur une île déserte, et un autre ingénieur de l’équipe peut simplement le lire et implémenter la solution comme vous l’avez décrit.,
Solutions alternatives
Qu’avez-vous considéré d’autre en proposant la solution ci-dessus? Quels sont les avantages et les inconvénients des solutions de rechange? Avez-vous envisagé d’acheter une solution tierce — ou d’utiliser une solution open source — qui résout ce problème plutôt que de construire la vôtre?
Testabilité, Surveillance et alerte
J’aime inclure cette section, parce que les gens traitent souvent cela comme une réflexion après coup ou sautent tout ensemble, et cela revient presque toujours pour les mordre plus tard quand les choses se cassent et ils n’ont aucune idée de comment ou pourquoi.,
Impact inter-équipes
Comment cela augmentera-t-il le fardeau des appels et des opérations de développement?
Combien ça coûte?
Provoque-t-il une régression de latence au système?
Expose-t-il des vulnérabilités de sécurité?
Quelles sont les conséquences négatives et les effets secondaires?
Comment l’équipe de support pourrait-elle communiquer cela aux clients?
Questions ouvertes
Toutes les questions ouvertes dont vous n’êtes pas sûr, les décisions litigieuses sur lesquelles vous aimeriez que les lecteurs se penchent, les travaux futurs suggérés, etc. Un nom ironique pour cette section est les « inconnues connues ».,
Cadrage et chronologie détaillés
Cette section sera principalement lue uniquement par les ingénieurs travaillant sur ce projet, leurs responsables techniques et leurs gestionnaires. Par conséquent, cette section est à la fin du doc.
Essentiellement, il s’agit de la ventilation de comment et quand vous prévoyez d’exécuter chaque partie du projet. Il y a beaucoup de choses qui entrent dans la portée avec précision, vous pouvez donc lire cet article pour en savoir plus sur la portée.
J’ai tendance à traiter également cette section du document de conception comme un suivi des tâches de projet en cours, donc je le mets à jour chaque fois que mon estimation de portée change., Mais c’est plus une question de préférence personnelle.
Comment l’écrire
Maintenant que nous avons parlé de ce qui se passe dans un bon document de conception, parlons du style d’écriture. Je promets que c’est différent de votre cours d’anglais au lycée.
Écrire aussi simplement que possible
N’essayez pas d’écrire comme les documents académiques que vous avez lus. Ils sont écrits pour impressionner les examinateurs de revues. Votre document est écrit pour décrire votre solution et obtenir les commentaires de vos coéquipiers., Vous pouvez obtenir plus de clarté en utilisant:
- Mots simples
- Phrases courtes
- Listes à puces et/ou listes numérotées
- Exemples concrets, comme « L’utilisateur Alice connecte son compte bancaire, puis …”
Ajouter beaucoup de graphiques et de diagrammes
Les graphiques peuvent souvent être utiles pour comparer plusieurs options potentielles, et les diagrammes sont généralement plus faciles à analyser que le texte. J’ai eu de la chance avec Google Drawing pour créer des diagrammes.,
Conseil de pro: n’oubliez pas d’ajouter un lien vers la version modifiable du diagramme sous la capture d’écran, afin que vous puissiez facilement le mettre à jour plus tard lorsque les choses changent inévitablement.
Inclure des nombres
L’ampleur du problème détermine souvent la solution. Pour aider les réviseurs à se faire une idée de l’état du monde, incluez des nombres réels tels que le nombre de lignes de base de données, le nombre d’erreurs utilisateur, la latence — et leur évolution en fonction de l’utilisation. Vous vous souvenez de vos notations Big-O?
Essayez d’être drôle
Un spec n’est pas un document académique. En outre, les gens aiment lire des choses drôles, donc c’est un bon moyen de garder le lecteur engagé., N’en faites pas trop au point de vous éloigner de l’idée de base.
Si vous, comme moi, avez du mal à être drôle, Joel Spolsky (évidemment connu pour ses talents comiques…) a ce conseil:
L’une des façons les plus simples d’être drôle est d’être précis quand ce n’est pas nécessaire Au lieu de dire « intérêts spéciaux”, dites « agriculteurs avacado gauchers. »
Faites le test sceptique
Avant d’envoyer votre document de conception à d’autres pour examen, faites-le passer en prétendant être l’examinateur. Quelles questions et quels doutes pourriez-vous avoir sur cette conception?, Ensuite, adressez-les préventivement.
Faites le test de vacances
Si vous partez en vacances maintenant sans accès à Internet, quelqu’un de votre équipe peut-il lire le document et le mettre en œuvre comme vous l’aviez prévu?
L’objectif principal d’un document de conception n’est pas le partage des connaissances, mais c’est un bon moyen d’évaluer pour plus de clarté afin que les autres puissent réellement vous donner des commentaires utiles.
Processus
Ah oui, la redoutable P-parole., Les documents de conception vous aident à obtenir des commentaires avant de perdre beaucoup de temps à mettre en œuvre la mauvaise solution ou la solution au mauvais problème. Il y a beaucoup d’art pour obtenir de bons commentaires, mais c’est pour un article ultérieur. Pour l’instant, parlons spécifiquement de la façon d’écrire le document de conception et d’obtenir des commentaires pour cela.
Tout d’abord, tous ceux qui travaillent sur le projet doivent faire partie du processus de conception. Ce n’est pas grave si le responsable technique finit par conduire beaucoup de décisions, mais tout le monde devrait être impliqué dans la discussion et acheter dans la conception., Donc, le” vous « tout au long de cet article est un” vous » vraiment pluriel qui inclut toutes les personnes sur le projet.
Deuxièmement, le processus de conception ne signifie pas que vous regardez les idées de théorisation du tableau blanc. N’hésitez pas à vous salir les mains et à prototyper des solutions potentielles. Ce n’est pas la même chose que de commencer à écrire du code de production pour le projet avant d’écrire un document de conception. Ne pas le faire. Mais vous devriez absolument vous sentir libre d’écrire du code jetable hacky pour valider une idée., Pour vous assurer que vous n’écrivez que du code exploratoire, faites en sorte qu’aucun de ce code prototype ne soit fusionné pour maîtriser.
Après cela, alors que vous commencez à avoir une idée de la façon de procéder pour votre projet, procédez comme suit:
- Demandez à un ingénieur expérimenté ou à un responsable technique de votre équipe d’être votre réviseur. Idéalement, ce serait quelqu’un qui est bien respecté et/ou familier avec les cas de bord du problème. Soudoyez – les avec boba si nécessaire.
- Aller dans une salle de conférence avec un tableau blanc.,
- Décrivez le problème que vous abordez à cet ingénieur (c’est une étape très importante, ne le sautez pas!).
- Expliquez ensuite l’implémentation que vous avez en tête et convainquez-les que c’est la bonne chose à construire.
Faire tout cela avant même de commencer à écrire votre document de conception vous permet d’obtenir des commentaires dès que possible, avant d’investir plus de temps et de vous attacher à une solution spécifique., Souvent, même si l’implémentation reste la même, votre réviseur est en mesure de signaler les cas d’angle que vous devez couvrir, d’indiquer les zones de confusion potentielles et d’anticiper les difficultés que vous pourriez rencontrer ultérieurement.
Ensuite, après avoir écrit une ébauche de votre document de conception, demandez au même réviseur de le relire et de l’estampiller en ajoutant son nom en tant que réviseur dans la section Titre et personnes du document de conception. Cela crée une incitation et une responsabilité supplémentaires pour l’examinateur.,
Sur cette note, envisagez d’ajouter des examinateurs spécialisés (tels que SREs et ingénieurs de sécurité) pour des aspects spécifiques de la conception.
Une fois que vous et le(s) réviseur (s) avez signé, n’hésitez pas à envoyer le document de conception à votre équipe pour obtenir des commentaires supplémentaires et partager les connaissances. Je suggère de limiter ce processus de collecte de commentaires à environ 1 semaine pour éviter des retards prolongés. Engagez-vous à répondre à toutes les questions et commentaires que les gens laissent dans la semaine. Laisser des commentaires suspendus = mauvais karma.,
Enfin, s’il y a beaucoup de discorde entre vous, votre réviseur et d’autres ingénieurs lisant le document, je recommande fortement de consolider tous les points de discorde dans la section Discussion de votre document. Ensuite, organisez une réunion avec les différentes parties pour parler de ces désaccords en personne.
Chaque fois qu’un fil de discussion contient plus de 5 commentaires, le passage à une discussion en personne a tendance à être beaucoup plus efficace. Gardez à l’esprit que vous êtes toujours responsable de faire l’appel final, même si tout le monde ne peut pas parvenir à un consensus.,
En parlant à Shrey Banga récemment à ce sujet, j’ai appris que Quip a un processus similaire, sauf qu’en plus d’avoir un ingénieur expérimenté ou un responsable technique dans votre équipe en tant qu’examinateur, ils suggèrent également d’avoir un ingénieur dans une autre équipe pour examiner le document. Je n’ai pas essayé cela, mais je peux certainement voir cela aider à obtenir des commentaires de personnes ayant des perspectives différentes et à améliorer la lisibilité générale du document.
Une fois que vous avez fait tout ce qui précède, il est temps de commencer la mise en œuvre!, Pour obtenir des points brownie supplémentaires, traitez ce document de conception comme un document vivant lorsque vous implémentez le design. Mettez à jour le document chaque fois que vous apprenez quelque chose qui vous amène à apporter des modifications à la solution d’origine ou à mettre à jour votre portée. Vous me remercierez plus tard lorsque vous n’aurez pas à expliquer les choses encore et encore à toutes vos parties prenantes.
Enfin, soyons vraiment méta une seconde: Comment évaluons-nous le succès d’un document de conception?
Mon collègue Kent Rakip a une bonne réponse à cela: un document de conception est réussi si le bon retour sur investissement du travail est effectué.,de l’architecture technique
X est la partie la plus risquée de l’architecture proposéeX d’abord pour réduire le risque du projetX n’est soit pas possible, soit beaucoup plus difficile que prévu à l’origineAu début de cet article, nous avons dit que l’objectif d’un document de conception est de s’assurer que le bon travail est fait., Dans l’exemple ci-dessus, grâce à ce document de conception, au lieu de perdre potentiellement des mois pour abandonner ce projet plus tard, vous n’avez passé que 8 jours. Cela me semble un résultat plutôt réussi.
Veuillez laisser un commentaire ci-dessous si vous avez des questions ou des commentaires! J’aimerais aussi savoir comment vous concevez différemment les documents dans votre équipe.
Donner du crédit là où le crédit est dû, j’ai appris beaucoup de ce qui précède en travaillant aux côtés de certains ingénieurs incroyables à Plaid (nous embauchons! Venez concevoir et construire des systèmes techniques doux avec nous) et Quora.,
Si vous aimez ce post, suivez-moi sur Twitter pour plus d’articles sur l’ingénierie, les processus et les systèmes dorsaux.