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