La culture des Design Docs chez Google (2020)

• Les design docs sont l’un des éléments centraux de la culture d’ingénierie logicielle de Google : ce sont des documents relativement informels rédigés par l’auteur principal d’un système logiciel ou d’une application avant de démarrer un projet de développement
  • Ils documentent la stratégie d’implémentation à haut niveau et les principales décisions de conception, en mettant particulièrement l’accent sur les compromis pris en compte au moment de ces décisions
  • Le travail d’un ingénieur logiciel ne consiste pas à écrire du code, mais à résoudre des problèmes ; dans les premières phases d’un projet, un texte non structuré comme un design doc peut être un outil de résolution de problème plus concis et plus facile à comprendre que le code

Rôle des design docs dans le cycle de vie du développement logiciel

• En plus de la documentation initiale de conception logicielle, ils remplissent aussi les fonctions suivantes :
  • Identifier tôt les problèmes de conception, tant que les changements coûtent encore peu
  • Faire émerger un consensus organisationnel autour de la conception
  • Garantir la prise en compte des préoccupations transverses (cross-cutting concerns)
  • Diffuser dans l’organisation les connaissances des ingénieurs seniors
  • Constituer la base de la mémoire organisationnelle sur les décisions de conception
  • Servir d’artefact de synthèse dans le portefeuille technique d’un concepteur logiciel

Structure d’un design doc

• Comme un design doc est un document informel sans règles strictes sur son contenu, la règle est de l’écrire dans le format le plus adapté au projet concerné
  • Context and scope : fournir une vue d’ensemble du contexte dans lequel le nouveau système est construit et de ce qui sera réellement développé
  • Goals and non-goals : lister les objectifs du système et ce qui n’en fait pas partie
  • The actual design
    • System-context-diagram : diagramme montrant le système comme une partie d’un environnement technique plus large
    • APIs : esquisse des API exposées par le système
    • Data storage : discussion sur la manière de stocker et gérer les données
    • Code and pseudo-code : à inclure uniquement pour expliquer de nouveaux algorithmes
    • Degree of constraint : le degré de contrainte de l’espace des solutions est l’un des facteurs majeurs qui influencent la forme du document de conception
  • Alternatives considered : lister les conceptions alternatives permettant raisonnablement d’atteindre un résultat similaire, puis expliquer les compromis de chacune et les raisons du choix final
  • Cross-cutting concerns : expliquer comment les préoccupations communes de l’organisation, comme la sécurité, la confidentialité ou l’observabilité, influencent la conception

Quand rédiger un design doc

• La décision d’écrire ou non un design doc dépend du fait que les bénéfices — consensus organisationnel sur la conception, documentation, revue par des seniors, etc. — dépassent ou non le travail supplémentaire que cela représente
  • Si la solution à un problème de conception n’est pas ambiguë, sauf en raison de la complexité du problème ou de la solution, la valeur du document est limitée
  • Un design doc trop proche d’un manuel d’implémentation peut être inutile
  • Pour le prototypage et les itérations rapides, la surcharge liée à la rédaction d’un design doc peut ne pas être adaptée

Cycle de vie d’un design doc

1. Creation and rapid iteration : rédaction du document et itérations rapides avec les collègues pour parvenir à une version stable
2. Review : partage avec un public plus large pour relecture
3. Implementation and iteration : mise à jour du document lorsque des changements de conception surviennent pendant l’implémentation
4. Maintenance and learning : servir de point d’entrée le plus accessible pour comprendre le système

Avis de GN⁺

• Un design doc est un bon moyen d’apporter de la clarté et de construire un consensus pour résoudre les problèmes les plus difficiles des projets logiciels complexes. Il peut réduire les coûts en évitant du développement inutile grâce à l’analyse préalable, mais il a aussi un coût en temps de rédaction et de relecture
• Il faut donc décider avec discernement, selon le projet, s’il convient d’écrire un design doc. Cela vaut la peine d’y réfléchir en cas d’incertitude sur la conception logicielle, si une intervention précoce d’ingénieurs seniors peut aider, si un consensus organisationnel est nécessaire sur la conception, si l’équipe néglige souvent des préoccupations communes comme la sécurité, ou si une documentation de haut niveau est nécessaire pour des systèmes legacy
• C’est un bon exemple qui montre l’importance de la documentation dans le processus de conception logicielle, et cela semble particulièrement utile pour établir une culture de conception cohérente dans les grandes équipes. Mais comme la charge documentaire peut rebuter les ingénieurs, il paraît important de définir des lignes directrices avec un niveau et un périmètre adaptés au contexte
• À titre personnel, je pense qu’un design doc est particulièrement utile pour 1) considérer les compromis selon la complexité de la conception, 2) découvrir tôt les problèmes de conception avant l’implémentation, et 3) fournir une vue d’ensemble du système afin d’accélérer l’apprentissage des nouveaux membres. Il faut toutefois veiller à ce qu’il ne devienne pas un document trop formel ou déconnecté de l’implémentation réelle
• Une autre approche pourrait être de rendre les design docs obligatoires uniquement au démarrage du projet ou dans les phases de conception les plus complexes, tout en offrant des incitations pour encourager les ingénieurs à en rédiger volontairement. Il serait aussi utile de souligner que cette documentation peut renforcer le portefeuille technique de chaque ingénieur

[GN⁺]

Avis Hacker News

Divers avis sur la culture des design docs chez Google :

• La rédaction de design docs est devenue un outil de promotion, si bien qu’elles sont souvent rédigées davantage pour les comités de promotion que pour les personnes qui construisent réellement les systèmes
• Types de design docs :
  • Design docs de promotion : mettent davantage en avant l’importance du projet et de l’entreprise que l’objectif réel du projet
  • Design docs de turbo-encapsulateur : remplies de jargon difficile à comprendre
  • Design docs de nouveaux employés : beaucoup de volume, peu de contenu
  • Design docs remplies de faits sans fondement : s’appuient sur des faits que « tout le monde connaît », mais qui ne sont en réalité pas vérifiés
• La conception fait partie d’un projet de développement, donc tout planifier dans un document avant de coder est une mauvaise approche
• Rédiger des documents à l’avance ne fait souvent que fournir un prétexte à des remarques mineures, alors qu’il vaut mieux résoudre les vrais problèmes en communiquant en amont avec les parties concernées
• Il est plus utile de collaborer en continu sur les documents et de les mettre à jour régulièrement
• Les ressources humaines gaspillées dans les design docs sont énormes
• La culture des design docs chez Amazon était excellente, mais elle n’avait plus de sens dans d’autres entreprises ayant repris l’approche de Google
• Il est arrivé que des retours sur une design doc arrivent tardivement alors même que le projet avançait déjà sans approbation
• Les design docs finissent parfois par remplacer la vraie documentation, ce qui conduit paradoxalement à une documentation de moindre qualité
• Les design docs ont aussi des avantages : elles aident à structurer la réflexion, à repérer les défauts, à fluidifier la communication et à estimer la charge de travail