Comment rédiger un bon document de conception de logiciel

En tant qu'ingénieur logiciel, je passe beaucoup de temps à lire et à rédiger des documents de conception. Après avoir parcouru des centaines de ces documents, j'ai constaté de première main une forte corrélation entre de bons documents de conception et le succès ultime 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 rédiger un document de conception
  • Ce qu'il faut inclure dans un document de conception
  • Comment l' écrire
  • Le processus qui l' entoure

Pourquoi rédiger un document de conception?

Un document de conception - également appelé spécification technique - est une description de la manière 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, c'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 obligeant à 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 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 l'objectif en eux-mêmes.

En règle générale, si vous travaillez sur un projet qui peut prendre 1 mois-ingénieur ou plus, vous devez rédiger un document de conception. Mais ne vous arrêtez pas là - beaucoup de petits projets pourraient également bénéficier d'un mini-document de conception.

Génial! 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, rédigent 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 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 considérery compris dans votre prochain document de conception:

Titre et personnes

Le titre de votre document de conception, leauteur (s) (doit être identique à la liste des personnes prévoyant de travailler sur ce projet), le ou les examinateursdu 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 est utile pour lui de lire le reste du document. Il devrait être de 3 paragraphes maximum.

Le contexte

Une description du problème en cours, pourquoi ce projet est nécessaire, ce que les gens doivent savoir pour évaluer ce projet et comment il s'intègre dans la stratégie technique, la stratégie produit ou les objectifs trimestriels de l'équipe.

Buts et non-buts

La section Objectifs devrait:

  • décrire l'impact de votre projet sur l'utilisateur - où votre utilisateur peut être une autre équipe d'ingénierie ou même un autre système technique
  • spécifier comment mesurer le succès à l'aide de métriques - des 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 résolvez pas afin que tout le monde soit sur la même longueur d'onde.

Jalons

Une liste de points de contrôle mesurables, afin que votre PM et le responsable de votre responsable puissent la parcourir et savoir à peu près quand les différentes parties du projet seront terminées. Je vous encourage à décomposer le projet en étapes majeures pour l'utilisateur si le projet dure plus d'un mois.

Utilisez des dates de calendrier afin de prendre en compte les retards, les vacances, les réunions, etc. Ça devrait ressembler a quelque chose comme ca:

Start Date: June 7, 2018

Milestone 1 — New system MVP running in dark-mode: June 28, 2018

Milestone 2 - Retire old system: July 4th, 2018

End Date: Add feature X, Y, Z to new system: July 14th, 2018

Ajoutez une [Update]sous-section ici si l'ETA de certains de ces jalons change, afin que les parties prenantes puissent facilement voir les estimations les plus à jour.

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.

Un utilisateurrécitest une excellente façon d'encadrer 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 section Architecture technique . Encore une fois, essayez de parcourir une user story pour concrétiser cela. N'hésitez pas à inclure de nombreuses sous-sections et schémas.

Donnez d'abord une vue d'ensemble, puis remplissez les lotsdedétails. Visez un monde où vous pouvez écrire ceci, puis prenez des vacances sur une île déserte, et un autre ingénieur de l'équipe pourra simplement le lire et mettre en œuvre la solution comme vous l'avez décrit.

Solutions alternatives

Qu'avez-vous pris en compte lors de l'élaboration de la solution ci-dessus? Quels sont les avantages et les inconvénients des alternatives? 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 créer la vôtre?

Testabilité, surveillance et alerte

J'aime inclure cette section, car les gens traitent souvent cela comme une réflexion après coup ou sautent tout ensemble, et cela revient presque toujours à les mordre plus tard quand les choses se cassent et qu'ils n'ont aucune idée de comment ou pourquoi.

Impact inter-équipes

Comment cela augmentera-t-il le fardeau des appels et des développeurs?

Combien cela coûtera-t-il?

Cela provoque-t-il une régression de la latence dans le système?

Expose-t-il des failles 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

Tous les problèmes en suspens dont vous n'êtes pas sûr, les décisions litigieuses sur lesquelles vous aimeriez que les lecteurs pèsent, les travaux futurs suggérés, etc. Un nom ironique pour cette section est les «inconnues connues».

Cadrage détaillé et chronologie

Cette section sera principalement lue uniquement par les ingénieurs travaillant sur ce projet, leurs responsables techniques et leurs responsables. Par conséquent, cette section est à la fin de la doc.

Essentiellement, il s'agit de la répartition de la façon et du moment où vous prévoyez d'exécuter chaque partie du projet. Il y a beaucoup de choses qui entrent dans le cadrage avec précision, vous pouvez donc lire ce post pour en savoir plus sur le cadrage.

J'ai également tendance à traiter cette section du document de conception comme un suivi des tâches du projet en cours, donc je la mets à jour chaque fois que mon estimation de la portée change. Mais c'est plus une 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 classe d'anglais au lycée.

Écrivez aussi simplement que possible

N'essayez pas d'écrire comme les articles académiques que vous avez lus. Ils sont écrits pour impressionner les critiques de revues. Votre document est rédigé pour décrire votre solution et obtenir les commentaires de vos coéquipiers. Vous pouvez obtenir de la 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…"

Ajoutez de nombreux graphiques et 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 de pouvoir facilement le mettre à jour plus tard lorsque les choses changent inévitablement.

Inclure les 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 la manière dont ils évoluent avec l'utilisation. Rappelez-vous vos notations Big-O?

Essayez d'être drôle

Une spécification n'est pas un article académique. De plus, les gens aiment lire des choses amusantes, c'est donc 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 de comique…) a cette astuce:

Une des façons les plus simples d'être drôle est d'être précis quand on ne le demande pas [… Exemple:] Au lieu de dire «intérêts particuliers», dites «cultivateurs d'avocat gauchers».

Faites le test sceptique

Avant d'envoyer votre document de conception à d'autres personnes pour examen, faites-le passer en faisant semblant d'être le réviseur. Quelles questions et doutes pourriez-vous avoir sur cette conception? Puis abordez-les de manière préventive.

Faites le test de vacances

Si vous partez maintenant pour de longues vacances sans accès à Internet, un membre de votre équipe peut-il lire le document et le mettre en œuvre comme vous le souhaitez?

L'objectif principal d'un document de conception n'est pas le partage des connaissances, mais c'est un bon moyen d'évaluer la clarté afin que les autres puissent réellement vous donner des commentaires utiles.

Processus

Ah oui, le mot P redouté . 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 le moment, parlons simplement de la manière d'écrire le document de conception et d'obtenir des commentaires.

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 un grand nombre de décisions, mais tout le monde devrait être impliqué dans la discussion et adhérer au design. Ainsi, 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 le tableau blanc théorisant des idées. N'hésitez pas à mettre la main à la pâte 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 fais pas ça. 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é avec master .

Après cela, lorsque vous commencez à avoir une idée de la façon de mener à bien votre projet, procédez comme suit:

  1. 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 extrêmes du problème. Les soudoyer avec du boba si nécessaire.
  2. Entrez dans une salle de conférence avec un tableau blanc.
  3. Décrivez le problème que vous abordez à cet ingénieur (c'est une étape très importante, ne l'ignorez pas!).
  4. Expliquez ensuite l' implémentation que vous avez à l'esprit et convaincez-les que c'est la bonne chose à construire.

Faire tout cela avant même de commencer à rédiger votre document de conception vous permet d'obtenir des commentaires le plus rapidement possible, avant d'investir plus de temps et de vous attacher à une solution spécifique. Souvent, même si la mise en œuvre reste la même, votre réviseur est en mesure de signaler les cas secondaires que vous devez couvrir, d'indiquer les zones de confusion potentielles et d'anticiper les difficultés que vous pourriez rencontrer plus tard.

Ensuite, après avoir rédigé un brouillon de votre document de conception, demandez au même réviseur de le lire à nouveau et tamponnez-le 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, pensez à ajouter des réviseurs spécialisés (tels que des SRE et des ingénieurs de sécurité) pour des aspects spécifiques de la conception.

Une fois que vous et le (s) réviseur (s) vous êtes déconnecté (s), n'hésitez pas à envoyer le document de conception à votre équipe pour des commentaires supplémentaires et le partage des connaissances. Je suggère de limiter dans le temps 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 les commentaires en suspens = mauvais karma.

Enfin, s'il y a beaucoup de désaccord entre vous, votre réviseur et les autres ingénieurs lisant le document, je recommande fortement de regrouper 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 comporte plus de 5 commentaires, passer à une discussion en personne a tendance à être beaucoup plus efficace. Gardez à l'esprit que vous êtes toujours responsable de l'appel final, même si tout le monde ne parvient pas à un consensus.

En discutant récemment avec Shrey Banga à ce sujet, j'ai appris que Quip avait un processus similaire, sauf qu'en plus d'avoir un ingénieur expérimenté ou un responsable technique dans votre équipe en tant que réviseur, ils suggèrent également qu'un ingénieur d'une autre équipe examine le document. Je n'ai pas essayé cela, mais je peux certainement voir que cela aide à 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 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, passons un instant à méta: comment évaluer le succès d'un design doc?

Mon collègue Kent Rakip a une bonne réponse à cela: un document de conception réussit si le bon retour sur investissement du travail est effectué. Cela signifie qu'un document de conception réussi peut en fait conduire à un résultat comme celui-ci:

  1. Vous passez 5 jours à rédiger le document de conception, cela vous oblige à réfléchir à différentes parties de l'architecture technique
  2. Vous obtenez des commentaires des réviseurs qui Xconstituent la partie la plus risquée de l'architecture proposée
  3. Vous décidez de mettre en œuvre en Xpremier pour réduire les risques du projet
  4. 3 jours plus tard, vous vous rendez compte que ce Xn'est pas possible ou bien plus difficile que ce que vous aviez initialement prévu
  5. Vous décidez d'arrêter de travailler sur ce projet et de prioriser d'autres travaux à la place

Au début de cet article, nous avons dit que le but 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 être un résultat plutôt réussi.

Veuillez laisser un commentaire ci-dessous si vous avez des questions ou des commentaires! J'aimerais également savoir comment vous concevez des documents différemment dans votre équipe.

Donnant du crédit là où le mérite est dû, j'ai appris beaucoup de choses ci-dessus en travaillant aux côtés d' incroyables ingénieurs chez Plaid (nous embauchons! Venez concevoir et construire de doux systèmes techniques avec nous) et Quora.

Si vous aimez cet article, suivez-moi sur Twitter pour plus d'articles sur l'ingénierie, les processus et les systèmes backend.