Comment rédiger un bon document de conception

• Un document de conception est un rapport technique qui organise la stratégie d’implémentation, les contraintes et les compromis d’un système
• Le document de conception sert à convaincre le lecteur que cette conception est adaptée au contexte
• La structure du document est importante, et le flux logique doit éviter que le lecteur soit pris au dépourvu par le contenu
• Grâce à la révision, il faut réduire les mots inutiles et préserver les ressources d’attention du lecteur
• L’utilisation de paragraphes courts et d’annexes, ainsi que l’amélioration des compétences rédactionnelles par la pratique, est essentielle

---

Définition

• Un document de conception est un rapport technique qui organise la stratégie d’implémentation d’un système dans le contexte des compromis et des contraintes

Objectif

• Comme une preuve en mathématiques permet de faire accepter un théorème, le document de conception a pour but de convaincre le lecteur que cette conception est optimale
• Dans le processus de conception, le simple fait d’écrire renforce la rigueur de la réflexion
• Rédiger un document de conception permet de transformer des idées vagues en réflexion concrète

Organisation

• La structure d’un bon document de conception est aussi importante que l’organisation du code
• De la même manière que les débutants écrivent du code, beaucoup ont tendance à produire des « documents de conception spaghetti »
• Si l’on aligne des phrases sans ordre logique, il devient difficile pour le lecteur de suivre le contexte et cela crée de la confusion
• Un document excellent doit avoir un flux naturel qui ne surprend pas le lecteur, et chaque phrase doit s’enchaîner comme une conséquence évidente de ce qui précède
• L’objectif est d’identifier l’état de réflexion du lecteur et de le guider progressivement vers un nouvel état
• Il faut désamorcer à l’avance les objections prévisibles et expliquer avant que le lecteur ne formule une contre-argumentation

Révision

• Une fois le contenu bien organisé, l’étape de suppression des mots inutiles (révision) devient essentielle
• La concentration du lecteur est une ressource limitée, et toute information superflue doit être supprimée sans hésitation
• Dans un premier jet, on peut réduire d’environ 30 % les formulations sans valeur
• En révisant les documents d’autres personnes et en développant un regard critique, on peut aussi affiner efficacement ses propres textes
• S’entraîner avec des tweets courts (limite de 280 caractères) aide également à simplifier sa pensée et à améliorer sa capacité de synthèse

Expérience et pratique

• Il n’existe pas de raccourci plus efficace que la pratique répétée pour progresser
• L’expérience de la culture centrée sur les documents chez Amazon a beaucoup aidé à améliorer les compétences rédactionnelles
• Lors des réunions importantes, on distribue des documents de conception de 1 à 6 pages, puis chacun les lit en silence et note ses remarques dans les marges
• Recevoir des retours permet d’améliorer concrètement son niveau en écriture

Conseils concrets

Utiliser des paragraphes courts

• Un document de conception doit créer un flux au moyen de bullet points concis et continus
• Chaque bullet point (observation, idée, problème, amélioration, etc.) doit être composé d’un court paragraphe centré sur un seul concept
• Chaque paragraphe doit être assez clair pour pouvoir être résumé en une phrase, ce qui permet d’économiser les ressources de mémoire à court terme du lecteur

Exploiter les annexes

• Les calculs complexes ou résultats de simulation doivent être détaillés dans des annexes plutôt que dans le corps du document, avec une simple mention sous forme de note dans le texte principal
• Les annexes ne sont pas indispensables pour comprendre les conclusions principales du corps du texte, mais elles sont fournies pour les lecteurs qui souhaitent aller plus loin

Exemple de révision

• (Avant révision, paragraphe verbeux) :

  Chaque bullet point doit constituer un paragraphe distinct dans le document. Chaque paragraphe doit pouvoir être résumé en une phrase. Il n’est pas nécessaire qu’il s’agisse réellement d’une seule phrase, car des explications supplémentaires peuvent être ajoutées pour développer le concept. Mais après lecture, le lecteur doit pouvoir le résumer en une phrase.

• (Après révision, paragraphe condensé) :

  Chaque bullet point doit former un paragraphe pouvant être résumé en une phrase. Il n’a pas besoin de n’être qu’une seule phrase, et l’on peut ajouter des précisions si nécessaire. Mais une fois lu, il doit pouvoir être condensé en une phrase.

Conclusion

• Le document de conception est un processus important qui permet de développer ses compétences grâce à la rigueur de la réflexion, au flux logique, à une révision centrée sur le lecteur et à une pratique répétée

[GN⁺]

Avis Hacker News

• Deux citations de l’article m’ont particulièrement marqué. La première, tirée d’une capture d’écran sur X, dit que « le processus d’écriture rend les idées 10 fois meilleures ». La seconde, au début, affirme que « la personne la plus importante à convaincre est l’auteur lui-même ». Je suis toujours surpris de voir qu’après des années dans l’industrie, certaines personnes restent opposées à la nécessité des documents de conception. Leslie Lamport disait que « l’écriture est la manière qu’a la nature de nous dire à quel point notre pensée est brouillonne ». Si vous voulez progresser en rédaction technique, je recommande l’article Write Like an Amazonian(https://medium.com/@apappascs/…)
  • Le conseil « remplacez les adjectifs par des données » semble s’être tellement répandu dans le secteur tech qu’aujourd’hui presque tous les CV que je vois sont remplis de chiffres au point qu’il devient difficile de comprendre ce qu’ils signifient
• En tant que reviewer de design, il y a un point que tous les rédacteurs de documents doivent absolument intérioriser. C’est l’idée que « les bons documents permettent au lecteur de comprendre le problème et le modèle de réflexion, de sorte que lorsque la solution, née après plusieurs semaines de réflexion, est enfin présentée, elle paraît naturellement convaincante ». Ma citation préférée reste « si j’avais eu plus de temps, j’aurais écrit une lettre plus courte ». Un document de conception doit simplifier des choses complexes, et ne devrait pas être l’endroit où l’on déverse sans filtre tous les détours et tous les échecs traversés par le développeur. Ces éléments peuvent bien sûr être utiles, mais il vaut mieux les consigner dans un document séparé ou en annexe. Il faut montrer simplement la voie à suivre
  • Je préfère la formule « plus de temps, une lettre plus courte »
  • Je me pose toujours ces questions : « Est-ce que ce sujet va déclencher une controverse inutile ? », « Est-ce que cette controverse vaut la peine d’avoir lieu ? » Mon objectif est de permettre à un nouveau lecteur d’entrer facilement dans la discussion, tout en évitant qu’une polémique n’émerge sur des points sans importance
• Les réunions chez Amazon commencent par la distribution d’un document rédigé en prose. Tout le monde s’assoit en silence, lit le document et note au stylo rouge des commentaires et des questions dans la marge. Je n’ai jamais travaillé chez Amazon, mais cette méthode semble étonnamment efficace, et tous ceux qui en parlent en gardent une impression positive. On pourrait croire que consacrer un temps de réunion précieux à simplement lire ensemble est inefficace, alors qu’une lecture préparatoire permettrait en théorie de faire des réunions plus courtes. Mais la lecture synchrone en temps réel finit souvent par faire attendre les lecteurs plus lents ou par laisser chacun avec un niveau de compréhension différent faute de contexte, ce qui rend le temps passé vaguement improductif. Chez Google, j’ai souvent vu des design reviews où la plupart des participants découvraient le document pour la première fois en entrant dans la discussion. À mon avis, c’est parce que Google n’avait pas de culture documentaire forte, et que le fait que les leads ou les managers arrivent eux aussi sans préparation était tacitement toléré. Rien qu’en installant une culture où l’on lit réellement les documents avant la réunion, le temps de réunion pourrait être utilisé bien plus efficacement
  • On dit souvent que si les gens lisent à l’avance, les réunions deviennent plus courtes, mais la pratique d’Amazon est justement une réponse au fait qu’en réalité les gens ne lisent pas en amont. Dans un ancien article sur le sujet, il était expliqué qu’il était en pratique presque impossible d’instaurer une culture forte de préparation préalable. Tous les participants sortaient d’une réunion précédente et n’avaient pas eu le temps de se préparer, tout comme pour cette réunion précédente. En théorie, on peut critiquer cela en disant qu’il suffirait de réduire le nombre de réunions, mais en pratique ces réunions avaient de la valeur, et les décisions étaient bien prises même en comptant le temps de lecture. Au final, il faut se concentrer sur les résultats, et chez Amazon on semble considérer que les avantages de cette méthode l’emportent sur ses inconvénients
  • Je me demande pourquoi le moment où l’on lit le document est si important. S’il faut plus de temps, on peut toujours allonger la réunion. L’inconvénient, c’est peut-être la difficulté à trouver un créneau, mais le temps total passé ne change pas
  • Je pense qu’on perd davantage de temps quand tout le monde n’a pas le même niveau de compréhension, ou quand on craint que quelqu’un passe à côté d’un corner case
  • Certains racontent d’expérience que si ce n’est pas traité en réunion, rien ne se passe
• Il y a beaucoup d’excellents conseils sur la clarté et l’editing. Le point faible, c’est la manière de gérer les documents une fois approuvés. Sans maintenance, on finit dans un état d’« archéologie du design ». Il y a quelques années, Andrew Harmel-Law a proposé les Architecture Decision Records (ADR) comme méthode efficace pour consigner les décisions d’architecture dans une organisation, et cela peut aider. Les ADR sont placés à côté du code, par exemple adr/001-use-postgres.md, et consignent brièvement le contexte, la décision et son statut. L’avantage, c’est qu’ils peuvent être relus facilement à chaque PR, remplacés facilement quand la situation change, et que la justification de la décision d’origine reste searchable même plusieurs mois plus tard. [Lien : https://martinfowler.com/articles/…]
  • Avec une telle approche, je me demande si les comités transverses de l’organisation — Security, Privacy, Compliance, etc. — deviennent reviewers sur chaque PR contenant un ADR. J’ai du mal à imaginer que ce type de PR puisse être mergé en moins de 90 jours
  • Il faudrait que je lise entièrement le lien MF.com(https://thoughtworks.com/radar/techniques/…), mais l’« Advice Process » semble se terminer par une injonction du type « parlez à tout le monde ». Toute personne portant un titre avec « Managing » risque probablement de décrocher à ce stade. Le vrai cœur du sujet semble être les « quatre éléments de soutien », mais en voulant en apprendre plus sur les ADR via ce lien, j’ai surtout fini par télécharger un PDF(https://thoughtworks.com/content/dam/…). J’aimerais qu’on m’explique clairement ce que sont concrètement les ADR
  • Session messenger est un bon exemple. Il y a eu tellement de changements de design et d’architecture qu’il n’existe plus d’information faisant autorité pour expliquer officiellement comment cela fonctionne. À titre personnel, si vous avez besoin d’une messagerie sécurisée, utilisez simplement Signal
• D’après mon expérience, l’organisation et la clarté sont les plus grands obstacles qui empêchent les ingénieurs logiciel de progresser en rédaction. La métaphore du « code spaghetti » utilisée par l’auteur est, à mon sens, un très bon moyen d’expliquer l’importance de l’organisation des idées. J’avais déjà essayé d’exprimer quelque chose de similaire autrement, mais je compte reprendre cette métaphore à l’avenir. J’avais écrit autrefois un billet de blog proche sur le sujet (https://ryanmadden.net/things-i-learned-at-google-design-docs/), et j’ai trouvé intéressants à la fois les points communs — comme la densité d’information et l’importance de la pratique — et les différences selon les entreprises. En revanche, je suis un peu moins d’accord avec l’idée des « paragraphes courts ». Des paragraphes courts n’apparaissent que lorsque l’information a déjà été bien retravaillée ; couper les lignes ne suffit pas à aider. Je trouve que la partie « Editing » explique mieux cette idée de fond
• J’ai un processus que j’utilise. Étape 1 : je vide dans un document tout ce qui me passe par la tête, sans ordre particulier ; on peut même essayer la dictée vocale. Étape 2 : j’essaie de faire structurer cela et de donner un flux logique par un LLM (grand modèle de langage). En réalité, je peux très bien jeter le résultat à ce stade ; cela fait partie du processus de clarification de la pensée. Étape 3 : à partir du résultat du LLM, ou bien en repartant complètement de zéro, j’écris un premier brouillon structuré. Étape 4 : je rends le tout aussi concis que possible, en supprimant des mots, en choisissant des termes plus simples, etc. Étape 5 : je répète l’étape 4. Le LLM sert de passerelle pour structurer un brouillon désordonné. Il faut aussi être prêt à jeter ce qu’il produit. On peut toujours couper au moins 30 %. Je suis encore surpris de constater qu’on peut réduire autant sans perdre le sens
  • J’ai l’impression que rééditer mon texte est presque aussi important que l’écrire la première fois. C’est à ce moment-là que je vois à quel point j’ai tiré certaines conclusions trop vite, ou ce que je n’ai pas pris en compte. Beaucoup de gens ne semblent pas accorder à l’écriture toute sa valeur comme outil de focalisation de la pensée. C’est pareil pour le code. Même quand on écrit juste un template banal, il arrive souvent qu’en rédigeant les tests on trouve des idées pour améliorer le code principal. En revanche, un LLM ne met pas en lumière ce type d’améliorations qualitatives
  • C’est une répétition d’expansion, de réduction, de compression, de nouvelle expansion, puis de nouvelle compression. Si quelqu’un pose une question précise, on ré-élargit ; et à la fin, on utilise un LLM pour faire un résumé léger, juste pour le plaisir. En somme, on est dans de véritables montagnes russes sans fin
• Je me dis qu’il faut que j’écrive davantage. Les deux grandes méthodes de structuration documentaire auxquelles je pense sont B.O.O. et Good Strategy/Bad Strategy. B.O.O. signifie Background, Objective, Overview : cela sert à expliquer comment on en est arrivé là, ce qu’on veut changer et de quelle manière. Good Strategy/Bad Strategy est un livre structuré autour du diagnostic, des lignes directrices / préconditions / exigences, puis des actions ; sur le plan de l’organisation documentaire, c’est assez proche de B.O.O. B.O.O. fonctionne bien chez Google ou dans des organisations de petite taille, tandis que Good Strategy/Bad Strategy peut s’appliquer à des structures bien plus variées, mais demande un auteur doté d’une vraie plume
• Suivre un cours de rédaction technique a beaucoup amélioré ma capacité à résumer clairement les points essentiels. On se concentrait sur la méthode du « couper au stylo rouge » : écrire, barrer, puis réécrire. L’objectif était d’apprendre à transmettre un concept avec le moins de mots possible. Ce processus comporte plusieurs étapes et devient plus facile avec la pratique. J’essaie aussi de partager cette compétence avec mes coéquipiers, tout en me rappelant qu’il s’agit d’une aptitude qu’il faut entretenir régulièrement
• J’aime beaucoup ce type de documents et, plus largement, cette culture de l’écrit. Mais j’ai aussi vu cette approche produire l’effet inverse. Expliquer les raisons et le raisonnement qui mènent à une conclusion est très efficace dans un document de persuasion. Pourtant, ce niveau de persuasion n’est pas toujours nécessaire. Parfois, il vaut mieux annoncer directement la conclusion, notamment pour les lecteurs qui font confiance à l’auteur. Bien souvent, les lecteurs veulent d’abord connaître l’essentiel plutôt que de s’épuiser à suivre tout le raisonnement. Une fois la conclusion comprise, ils ont alors envie de regarder les détails logiques
  • Mettre un résumé en haut, puis enchaîner en dessous avec l’explication détaillée et les justifications, fonctionne très bien aussi
• Il m’arrive souvent d’écrire des documents de design que je serai peut-être le seul à lire. Le simple fait de poser le document par écrit me semble déjà très puissant. J’aimerais vraiment avoir des exemples concrets de documents pour pouvoir comparer ma structure avec la structure finale adoptée par d’autres personnes