- Chez Google, un Design Doc est un document rédigé avant de coder pour structurer le contexte du problème, la stratégie d’implémentation de haut niveau et les décisions de conception clés, afin de réduire les risques tant que le coût de conception reste faible
- La valeur du document ne réside pas tant dans l’explication du code final que dans la mise en évidence des trade-offs et des alternatives, afin que l’organisation partage les mêmes bases de décision
- Un bon Design Doc contient, selon le projet, le contexte et le périmètre, les objectifs et non-objectifs, la conception elle-même, les alternatives envisagées, ainsi que des préoccupations transverses comme la sécurité, la confidentialité et l’observabilité
- Si la conception est déjà évidente ou que le document se contente d’énumérer la procédure d’implémentation, la charge de rédaction et de revue du Design Doc peut dépasser ses bénéfices
- Le document s’inscrit dans un cycle qui va de la rédaction à la revue, puis aux mises à jour pendant l’implémentation, jusqu’à la maintenance et à l’apprentissage ; si la conception change avant le lancement, il vaut mieux mettre le document à jour lui aussi
Le rôle d’un Design Doc
- Chez Google, un Design Doc est un document relativement informel créé par l’auteur principal d’un système logiciel ou d’une application avant de démarrer un projet de développement
- Il décrit la stratégie d’implémentation de haut niveau et les décisions de conception essentielles, mais l’important n’est pas une simple liste de décisions : ce sont les trade-offs qui montrent pourquoi ces choix ont été faits
- L’objectif de l’ingénierie logicielle n’est pas de produire du code pour lui-même, mais de résoudre des problèmes ; au début d’un projet, un texte non structuré peut donc être plus concis et plus facile à comprendre que du code
- Le Design Doc joue plusieurs rôles dans le cycle de vie du développement
- Il permet d’identifier tôt les problèmes de conception, quand le coût du changement est encore faible
- Il aide à construire un consensus de conception au sein de l’organisation
- Il évite d’oublier des préoccupations transverses comme la sécurité, la confidentialité ou l’observabilité
- Il permet de diffuser dans l’organisation les connaissances des ingénieurs seniors
- Il conserve une mémoire organisationnelle des décisions de conception
- Il constitue un livrable qui résume le portefeuille technique du concepteur
Structure de base d’un Design Doc
- Il n’existe pas de modèle strict pour un Design Doc ; le premier principe consiste à choisir le format le plus adapté au projet concerné
- Cela dit, une structure souvent utile comprend le contexte et le périmètre, les objectifs et non-objectifs, la conception elle-même, les alternatives étudiées, les préoccupations transverses, ainsi qu’une longueur appropriée
-
Contexte et périmètre
- Cette section fournit une vue d’ensemble grossière de l’environnement dans lequel s’insère le nouveau système et de ce qui sera réellement construit
- Ce n’est pas un document d’exigences, donc elle doit rester concise et viser surtout à permettre au lecteur de rattraper rapidement le contexte
- On peut supposer certaines connaissances préalables et renvoyer les détails vers des liens
- Cette section doit se concentrer sur des faits de contexte objectifs
-
Objectifs et non-objectifs
- Les objectifs du système, ainsi que parfois des non-objectifs encore plus importants, sont résumés sous forme de courtes listes à puces
- Un non-objectif n’est pas la simple négation d’un objectif, comme « le système ne doit pas planter » ; c’est un élément qui aurait pu devenir un objectif mais qui est explicitement exclu
- En conception de base de données, la conformité ACID est un bon exemple d’élément dont il faut savoir s’il s’agit d’un objectif ou d’un non-objectif
- Même si c’est un non-objectif, on peut choisir une solution qui offre tout de même cette propriété, à condition que cela n’introduise pas de trade-off nuisible à l’atteinte des objectifs
Comment rédiger la conception elle-même
- La section consacrée à la conception doit partir d’une vue d’ensemble puis descendre progressivement dans le détail
- Le Design Doc est l’endroit où l’on consigne les trade-offs apparus dans la conception logicielle
- À partir des faits de contexte, ainsi que des exigences que constituent les objectifs et non-objectifs, il faut proposer une solution et montrer pourquoi une solution donnée répond le mieux aux objectifs
- L’avantage du format documentaire est de permettre de choisir avec souplesse le mode de représentation le plus adapté à l’ensemble de problèmes traité
-
Diagramme de contexte système
- Dans beaucoup de documents, un diagramme de contexte système peut être utile
- Ce diagramme présente le système comme une partie d’un environnement technique plus large et aide le lecteur à comprendre la nouvelle conception à l’intérieur d’un cadre qu’il connaît déjà
-
API et stockage des données
- Si le système conçu expose une API, il est généralement utile d’en faire une esquisse
- Il faut éviter de copier-coller telles quelles les définitions d’interface formelles ou les schémas de données
- Ces définitions deviennent facilement verbeuses, incluent des détails inutiles et peuvent vite devenir obsolètes
- Il vaut mieux se concentrer sur les éléments pertinents pour la conception et les trade-offs
- Un système qui stocke des données doit expliquer comment ces données sont stockées et sous quelle forme générale
- Plutôt que de coller la définition complète du schéma, mieux vaut décrire les parties liées aux arbitrages de conception
-
Code et pseudocode
- Il vaut mieux mettre très peu de code dans un Design Doc
- Sauf pour expliquer un nouvel algorithme, le pseudocode doit lui aussi être utilisé avec parcimonie
- S’il existe un prototype démontrant que la conception est réalisable, on peut le lier de manière appropriée
Le niveau de contrainte change la forme du document
- L’un des principaux facteurs qui influencent la conception logicielle et la forme du Design Doc est le degré de contrainte de l’espace des solutions
- À une extrémité, on trouve les projets logiciels greenfield où seuls les objectifs sont donnés, tandis que la solution peut prendre presque n’importe quelle forme
- Ces documents peuvent couvrir un périmètre large, mais ils doivent rapidement définir des règles pour réduire l’espace des solutions à un ensemble gérable
- À l’autre extrémité, on trouve des systèmes où les solutions possibles sont bien définies, mais où la manière de les combiner pour atteindre les objectifs reste peu claire
- Il peut s’agir de systèmes legacy difficiles à modifier
- Ou de la conception d’une bibliothèque qui doit fonctionner dans les contraintes imposées par le langage hôte
- Dans ce cas, on peut lister des actions relativement faciles à réaliser, mais il faut les combiner de manière créative pour atteindre les objectifs
- Si plusieurs solutions sont toutes imparfaites, le document doit se concentrer sur le choix de la meilleure approche au regard des trade-offs identifiés
Alternatives et préoccupations transverses
-
Alternatives envisagées
- Cette section énumère les conceptions alternatives qui auraient raisonnablement pu produire un résultat similaire
- Elle doit mettre l’accent sur les trade-offs générés par chaque option et sur la manière dont ces arbitrages ont conduit au choix final
- Les solutions non retenues peuvent être traitées brièvement, mais cette section est très importante dans le document
- Il faut montrer pourquoi d’autres solutions auxquelles le lecteur pourrait penser sont moins souhaitables au regard des objectifs du projet
-
Préoccupations transverses
- Grâce à cette section, une organisation peut s’assurer que des préoccupations transverses comme la sécurité, la confidentialité ou l’observabilité sont toujours prises en compte
- Il s’agit généralement de courtes sections expliquant l’impact de chaque sujet sur la conception et la manière dont il est traité
- Chaque équipe doit déterminer quelles préoccupations doivent être considérées comme standard dans son contexte
- Chez Google, les projets exigent un Design Doc dédié à la confidentialité, ainsi que des revues spécifiques sur la confidentialité et la sécurité, en raison de leur importance
- L’achèvement de ces revues est requis avant la mise en production du projet
- La bonne pratique consiste à collaborer avec les équipes confidentialité et sécurité le plus tôt possible afin que la conception les intègre dès le départ
- S’il existe un document dédié à ce sujet, le Design Doc central peut s’y référer sans répéter les détails
Longueur et cas où il n’est pas nécessaire d’en rédiger un
-
Longueur appropriée
- Un Design Doc doit être assez détaillé, tout en restant suffisamment court pour que des personnes très occupées puissent réellement le lire
- Pour les grands projets, un ordre de grandeur de 10 à 20 pages semble approprié
- Si le document devient bien plus long, il peut être préférable de découper le problème en sous-problèmes plus gérables
- Il est aussi possible de rédiger des mini Design Docs de 1 à 3 pages
- Ils sont particulièrement utiles pour les améliorations incrémentales ou les sous-tâches de projets agiles
- Ils suivent les mêmes étapes que les documents longs, mais de façon plus concise et sur un ensemble de problèmes plus limité
-
Cas où il n’est pas nécessaire d’en rédiger un
- Rédiger un Design Doc implique une certaine charge
- La décision d’en écrire un dépend du fait que les bénéfices attendus — consensus de conception, documentation, revue par des seniors, etc. — dépassent ou non le coût de production du document
- Le principal critère de jugement est le niveau d’ambiguïté du problème de conception
- Cette ambiguïté peut venir de la complexité du problème, de la complexité de la solution, ou des deux
- Si la situation n’est pas ambiguë, la valeur du processus de rédaction est faible
- Si le document est en pratique un manuel d’implémentation, un Design Doc n’est peut-être pas nécessaire
- S’il se contente de dire « voici comment on va implémenter cela » sans expliquer les trade-offs, les alternatives et les décisions, il aurait peut-être mieux valu écrire directement le programme
- Si la solution est tellement évidente qu’il n’y a pas de trade-off, la valeur du document diminue
- La charge de rédaction et de revue d’un Design Doc peut ne pas convenir au prototypage et aux itérations rapides
- Suivre une méthodologie agile ne dispense pas de réfléchir sérieusement à la solution d’un problème connu
- Le prototypage lui-même peut faire partie de la rédaction du Design Doc, et le fait de pouvoir dire « on l’a essayé et ça fonctionne » peut constituer un argument très fort en faveur d’un choix de conception
Cycle de vie d’un Design Doc
- Le cycle de vie d’un Design Doc comporte quatre étapes
- Rédaction et itération rapide
- Revue
- Implémentation et itération
- Maintenance et apprentissage
-
Rédaction et itération rapide
- Le document peut être rédigé seul par son auteur ou en co-rédaction avec d’autres personnes
- Il est ensuite partagé avec les collègues qui connaissent le mieux l’espace du problème, afin d’itérer rapidement
- Leurs questions de clarification et leurs suggestions conduisent le document vers une première version relativement stable
- Chez Google, certaines équipes et certains ingénieurs préfèrent créer leurs documents avec des outils de gestion de versions et de code review, mais la majorité des Design Docs sont rédigés dans Google Docs et utilisent largement ses fonctions de collaboration
-
Revue
- Lors de la phase de revue, le document est partagé avec un public plus large que les seuls collaborateurs proches de l’auteur initial
- La revue peut apporter une grande valeur, mais elle peut aussi devenir un piège en termes de charge, et doit donc être menée avec prudence
- L’approche légère consiste à envoyer le document à une mailing list d’équipe plus large afin que chacun puisse le consulter
- Les discussions ont principalement lieu dans les fils de commentaires du document
- L’approche plus lourde est une réunion formelle de revue de conception, où l’auteur présente le document devant des ingénieurs seniors
- Beaucoup d’équipes chez Google organisent des réunions régulières pour ce type de revue
- Attendre ces réunions peut ralentir fortement le processus de développement
- On peut atténuer ce problème en sollicitant directement les retours les plus importants et en évitant de faire de la revue élargie un bloqueur de progression
- Quand Google était une entreprise plus petite, il était courant d’envoyer les conceptions à une mailing list centrale unique, que les ingénieurs seniors examinaient lorsqu’ils avaient du temps
- Cette approche avait l’avantage de créer à l’échelle de l’entreprise une culture de conception logicielle relativement homogène
- Avec la forte croissance de l’organisation d’ingénierie, il est devenu difficile de maintenir cette approche centralisée
- La valeur principale de la revue est de donner à l’expérience collective de l’organisation l’occasion d’influencer la conception
- La phase de revue aide de manière constante à faire en sorte que la conception prenne en compte des préoccupations transverses comme l’observabilité, la sécurité et la confidentialité
- La valeur essentielle de la revue n’est pas seulement de découvrir des problèmes, mais de les découvrir tôt dans le cycle de développement, lorsque le coût du changement est encore faible
-
Implémentation et itération
- Une fois acquis le fait qu’il est peu probable que des revues supplémentaires imposent de grands changements à la conception, il est temps de commencer l’implémentation
- Lorsque le plan se confronte à la réalité, des défauts, des exigences non traitées et des hypothèses erronées peuvent apparaître, rendant des changements de conception nécessaires
- Dans ce cas, il est fortement recommandé de mettre à jour le Design Doc
- Règle pratique : tant que le système conçu n’a pas encore été lancé, il faut impérativement mettre le document à jour
- En pratique, les gens mettent rarement bien leurs documents à jour, et pour diverses raisons opérationnelles, les changements sont souvent séparés dans de nouveaux documents
- Le résultat peut alors ressembler moins à un document cohérent qu’à une constitution américaine couverte d’amendements
- Le fait d’ajouter depuis le document d’origine des liens vers ces documents d’amendement aide énormément les mainteneurs ultérieurs à comprendre le système concerné en faisant une véritable archéologie des Design Docs
-
Maintenance et apprentissage
- Quand un ingénieur Google découvre un système qu’il n’a jamais touché auparavant, l’une des premières questions posées est souvent : « Où est le Design Doc ? »
- Comme tout autre document, un Design Doc a tendance à s’écarter de la réalité avec le temps, mais il reste souvent le point d’entrée le plus accessible pour comprendre le raisonnement qui a conduit à la création du système
- Il est utile pour l’auteur de relire son propre Design Doc un ou deux ans plus tard
- Pour voir ce qu’il avait bien anticipé
- Pour voir ce qu’il avait mal évalué
- Pour réfléchir à ce qu’il déciderait différemment aujourd’hui
- Répondre à ces questions aide à progresser comme ingénieur et à améliorer avec le temps ses compétences en conception logicielle
Décider quand commencer par un Design Doc
- Un Design Doc est un bon moyen de gagner en clarté et de construire un consensus lorsqu’on s’attaque à des problèmes difficiles dans un projet logiciel
- Il peut réduire les impasses de développement qui auraient pu être évitées par une réflexion préalable, et donc faire économiser des coûts
- En même temps, sa rédaction et sa revue prennent du temps, ce qui représente aussi un coût
- On peut se poser les questions suivantes
- La bonne conception logicielle est-elle incertaine, au point qu’il soit pertinent d’investir du temps en amont pour gagner en confiance ?
- Est-il utile d’impliquer des ingénieurs seniors dès la phase de conception, alors qu’ils ne pourront peut-être pas relire toutes les modifications de code ?
- La conception logicielle est-elle ambiguë ou controversée, au point qu’un consensus organisationnel ait de la valeur ?
- L’équipe oublie-t-elle parfois, dans la conception, la confidentialité, la sécurité, la journalisation ou d’autres préoccupations transverses ?
- L’organisation a-t-elle un fort besoin de documents offrant une vision de haut niveau de la conception de ses systèmes legacy ?
- Si vous répondez « oui » à au moins 3 de ces questions, il est très probable qu’un Design Doc soit une bonne manière de démarrer votre prochain projet logiciel
1 commentaires
Avis sur Hacker News
J’ai quitté l’entreprise à cause de la culture des documents de conception de Google.
Peu après mon arrivée, j’ai rédigé un document très détaillé pour une tâche relativement mineure que j’avais déjà effectuée plusieurs fois dans d’autres domaines produit, et un collègue m’a pris à part pour me dire : « ici, on ne fait pas comme ça ».
L’approche que je proposais n’était qu’une petite variante de la méthode recommandée, mais on m’a demandé « d’évaluer davantage de façons de mener ce travail à bien » ; quand j’ai demandé pourquoi, on m’a répondu que cela « montre que l’on a envisagé largement les possibilités ».
Il existe clairement du faux travail chez Google, et j’aurais aimé rejoindre une autre équipe.
La culture de Google est devenue un culte du cargo qui s’imite elle-même.
Dans certaines entreprises où j’ai travaillé après Google, on évitait de discuter en détail du processus de promotion, parce qu’on avait vu ce qui se passe quand les gens se mettent à le micro-optimiser.
Comme tout le monde est occupé, on ne peut pas discuter rapidement en tête-à-tête avec chacun ; si l’examen par les parties prenantes n’est pas correctement fait, des personnes mécontentes risquent de venir vous voir et de vous forcer à annuler le lancement.
Dans ce contexte, les documents de conception sont un outil de communication asynchrone pour des sujets riches en information. Si le produit réussit, dix ans plus tard vous continuerez à dialoguer via ces documents avec les personnes qui rejoindront l’équipe.
J’ai été sauvé plusieurs fois par un document de conception quelconque datant de 2010 qui expliquait une décision étrange nous bloquant encore aujourd’hui. Ce n’est peut-être pas adapté aux petites équipes agiles ni aux tâches moins complexes, mais même si c’est devenu un culte du cargo dans la culture d’ingénierie, il y a généralement des raisons et un contexte derrière.
Si vous concevez quelque chose et que vous n’envisagez qu’une seule solution, alors soit il n’y a pas de conception, soit elle n’est pas assez rigoureuse. Les options et les compromis sont ce qui fait la conception.
Beaucoup de ces personnes sont des consultants externes qui travaillent avec l’entreprise depuis plus de 15 ans ; comme ce sont les mêmes personnes qui effectuent les mêmes tâches depuis longtemps, il existe déjà dans une certaine mesure des standards. Pourtant, elles s’efforcent quand même de brandir l’épouvantail du « que se passe-t-il si les gens ne suivent pas les standards ? ».
Résultat : les documents de conception sont inexistants ou terriblement obsolètes, et l’entreprise continue chaque année d’employer les mêmes consultants à des coûts gonflés.
Aujourd’hui, je suis dans une équipe où il y a beaucoup de vieux Googlers avec plus de 15 ans d’ancienneté, et les documents de conception n’existent que lorsqu’ils sont nécessaires : quand cela touche plusieurs systèmes, quand il y a beaucoup de compromis et que la complexité est manifeste, etc. Sinon, c’est simplement du genre « rédige un CLS ».
Chez Google, les documents de conception semblent poser problème parce qu’ils constituent un élément clé des dossiers de promotion.
Ils sont donc rédigés en pensant davantage au comité de promotion qu’aux personnes qui travailleront réellement sur le système, leur lectorat naturel.
À chaque fois que j’arrive dans une nouvelle entreprise, je propose de commencer à rédiger des documents de conception, et cela fait immédiatement bonne impression auprès de la direction :)
Dans beaucoup de documents que j’ai lus, on avait l’impression que la décision souhaitée était déjà prise, puis qu’au début du document on avait ajouté deux options ou plus fabriquées pour mettre cette décision en valeur. L’une était trop simpliste, l’autre inutilement surconçue, puis on choisissait l’option qui paraissait raisonnable.
Comme on ne sait pas quel document de conception servira dans le dossier de promotion, même les plus petites tâches sont toutes consignées sous forme de document de conception. Il existe bien la notion de document de conception d’une page, mais en général cela passe d’une page à plusieurs.
Des documents de conception sont écrits même pour des projets d’une semaine, et il m’est arrivé de devoir relire des documents de conception de 20, 30 ou 40 pages qui, dans une autre entreprise, auraient tenu dans un seul ticket JIRA.
Beaucoup de gens ont appris que le comité de promotion veut voir des « documents écrits par l’auteur seul » ; que ce soit vrai ou non, cette croyance ralentit tout et freine l’apprentissage transversal. J’ai même vu des ingénieurs logiciel rester isolés pendant plus d’un trimestre à ne faire qu’écrire des documents de conception.
Dans un document de conception, la conception réelle devrait être le cœur du sujet, mais les 99 % restants sont de la définition du problème. Trop souvent, pendant la revue, on améliorait la définition du problème, ce qui obligeait à abandonner la conception et à réécrire la majeure partie du document.
Le pire, c’est quand l’amélioration de la définition du problème révèle une solution simple ne nécessitant pas de conception complexe. L’auteur a investi beaucoup de temps dans une conception complexe et, historiquement, de nombreux comités ont considéré cette complexité comme un argument de promotion, donc il résiste à la solution simple.
J’ai aussi vu des documents de conception qui ne présentaient aucune alternative. Ce n’était qu’une description laborieuse de choses à faire, ou de choses que quelqu’un voulait faire.
À force, les documents de conception finissent, vus de loin, par ressembler à un système de suivi de bugs. Tout le monde travaille sur son propre document de conception et personne ne travaille sur les bugs. Parce que les bugs ne permettent pas d’obtenir une promotion.
Quand on rejoint une nouvelle équipe, on vous dit qu’il suffit de lire les documents de conception, mais en pratique ils ne sont souvent pas suivis de manière centralisée. Dans beaucoup d’équipes, les documents de conception n’appartiennent pas à l’équipe ni au projet, mais à des individus, parce que cela permet de garantir que personne d’autre n’y a contribué ; là encore, à cause du comité de promotion.
Il y a aussi beaucoup de documents de conception auxquels on n’a pas accès, non pas parce qu’ils sont top secret, mais simplement parce que c’est configuré ainsi. Ce n’est pas comme si une équipe avait deux ou trois documents de conception : il y en a une montagne à lire. Avec un cycle de mobilité chez Google d’environ deux ans, beaucoup de documents disparaissent dans le temps.
Dans une autre entreprise, ce serait un peu comme dire à quelqu’un qui rejoint une nouvelle équipe : « Tout ce dont tu as besoin, c’est de lire tous les bugs fermés ou tous les messages de commit de la branche principale. »
Ailleurs, on aurait probablement attrapé la personne après le déjeuner pour passer quelques heures avec l’équipe devant un tableau blanc à définir le problème. Les seniors auraient appris en temps réel aux juniors comment réfléchir à ce type de problème, avec des itérations rapides.
La plupart des choses auraient été écrites dans le système de suivi de bugs, ou, pour un gros sujet, dans un wiki ou un dossier de projet, afin d’en faire une propriété collective.
Tous les problèmes ci-dessus peuvent être améliorés, et j’ai effectivement essayé de les améliorer, mais la culture change lentement. Le concept même de document de conception est bon, mais il comporte des pièges, et la manière dont beaucoup de gens chez Google l’utilisent n’est pas la bonne réponse.
Les documents de conception dont la valeur dépassait le coût me manquent.
Dans l’ensemble, je n’ai pas vu cette stratégie fonctionner.
En revanche, il y avait de longs documents destinés à fournir du contexte, qui résumaient ce que l’équipe avait fait, ce qu’elle faisait, quels étaient les problèmes, etc., et ceux-là avaient tendance à être longs et exagérés.
Je travaille dans l’entreprise mentionnée, mais mon expérience n’est pas la même que celle de l’auteur
Il existe plusieurs types de documents de conception, et aucun de ceux-là ne m’a été utile. J’ai rarement vu chez Google des documents de conception utiles. Les documents de conception me donnent l’impression d’être faits pour des ingénieurs excessivement procéduriers
Les types que j’ai vus ressemblent grosso modo à ceci : les documents de conception pour promotion n’expliquent pas ce qu’ils cherchent à résoudre, ils se contentent de dire à quel point ce projet est formidable et rend l’entreprise meilleure. La conclusion logique est que l’auteur devrait être promu
Les documents de conception Turbo Encabulator sont des bavardages techniques remplis de termes qu’on n’a jamais vus, impossibles à comprendre sauf si l’on est senior dans l’équipe. Parfois, je ne suis même pas sûr que les seniors les comprennent
Les documents de conception de jeunes diplômés sont des documents vides de contenu, mais étirés autant que possible par quelqu’un qui sort tout juste de l’université et cherche à prouver quelque chose. Ils ne transmettent pas d’information et, souvent, remplissent environ 70 pages en copiant-collant en grand volume du code déjà écrit
Les documents de conception à faits inventés sont remplis de « tout le monde sait », « tout le monde le dit ». Ce n’est pas aussi flagrant que chez les politiciens, mais ils poussent leur propre conception avec des formules du type « cela suit les bonnes pratiques », « ce logiciel est lent, donc… ». Il manque qui a défini ces bonnes pratiques, pourquoi ce sont de bonnes pratiques, ce qui est lent, si cela a été mesuré, ou si c’est seulement le ressenti de l’utilisateur final
99 % des documents de conception que j’ai vus étaient comme ça. Il y a des exceptions, mais d’après mon expérience elles sont très rares. Je suis surpris que l’auteur pousse cette pratique. Cela dit, il était directeur et non ingénieur, donc à ce poste les documents de conception ont peut-être du sens ; je ne sais toujours pas quelle valeur apportent ces personnes
[1] https://en.wikipedia.org/wiki/Turbo_encabulator
Une chose qui m’avait frappé au début, c’est que les documents de conception conservés dans Google Docs avaient tendance à être de moins bonne qualité que ceux présents dans le dépôt de gestion de versions. Je ne sais pas si c’était un indicateur indirect de leur période de rédaction, ou si le processus de code review était plus strict que l’édition dans Docs
Quand j’ai écrit un gros document de conception, probablement autour de 40 pages, je l’ai fait comme le voulait l’usage en HTML écrit à la main, puis je l’ai fait passer par le système de code review. Je l’ai aussi publié sur la liste de diffusion centrale et le serveur web, et c’était appréciable de recevoir des retours de l’employé numéro 3. Comme ils étaient classés par catégorie dans un emplacement central, ils étaient faciles à trouver
Je ne me souviens pas qu’un seul document de conception ait pesé assez lourd pour être important dans une promotion à l’époque. Une promotion devait porter sur l’impact global, pas sur un livrable précis. Bien sûr, le système avait de gros défauts et produisait souvent des décisions surprenantes dans le mauvais sens, mais à ce moment-là je ne me souviens pas avoir lu de documents de conception optimisés pour l’évaluation de performance
Si vous pouvez trouver le site web qui rassemble les anciens documents de conception en HTML écrits à la main, je vous recommande de les parcourir. Ils vous sembleraient peut-être plus utiles si le système de l’époque était encore en production
Certains anciens documents, comme SmartASS, étaient remplis d’explications détaillées sur les équations et modèles sous-jacents, et aidaient énormément à comprendre le fonctionnement et pourquoi cette approche avait été choisie. Ils ont ensuite influencé mon propre travail de conception. Je n’étais pas directeur, juste ingénieur, et ils m’ont vraiment aidé
Parmi les documents de conception de Chrome liés depuis le site chromium.org, certains m’ont aussi aidé par le passé à comprendre l’architecture
Ils obligent les développeurs juniors à réfléchir à la solution en amont et à justifier leurs décisions, tout en permettant aux développeurs seniors de valider ces décisions et de donner du feedback asynchrone
Cela dit, j’ai toujours travaillé en startup et jamais dans une organisation d’ingénierie de plus de 30 à 40 personnes. La Big Tech est sans doute différente, mais mon expérience a été positive
De même, si expliquer quelque chose à un autre ingénieur prend longtemps, ne serait-ce qu’environ 30 minutes, il faut écrire un document pour gagner du temps
Je ne vois pas comment on peut penser qu’il n’est jamais nécessaire d’écrire de documentation
Plus tard, au moment de préparer une promotion, on finit par ajouter assez de contexte aux documents de la catégorie 2 pour en faire des documents de la catégorie 1
La documentation est généralement une bonne chose, mais cette approche me semble avoir des défauts
On dit qu’« avant de se lancer dans un projet de codage », l’auteur principal d’un système logiciel ou d’une application rédige un document relativement informel, mais la conception elle-même est le projet de codage, ce sont la même chose
L’idée qu’on puisse résoudre toute la conception sur papier avant de committer du code est fausse. L’approche par document de conception reconnaît d’ailleurs qu’il faut écrire un peu de code au début, mais tente de le cantonner strictement à un « prototype montrant que la conception est implémentable »
Une grande caractéristique des documents de conception préalables est qu’ils donnent aux gens l’autorisation de chipoter, c’est-à-dire de faire une review, avant le vrai codage. D’après mon expérience, le document grossit alors avec toujours plus de réserves et de discussions d’alternatives sans intérêt, et devient moins un document de conception qu’un document « par pitié, laissez-moi maintenant construire ça »
S’il y a des problèmes d’architecture importants nécessitant un changement de direction, mieux vaut en parler à l’avance avec les bonnes personnes et collaborer, plutôt que de produire un document de conception détaillé pour se le faire abattre ensuite
Si l’on reste plus proche de l’idée d’un « document relativement informel » et qu’on le met à jour au fil de l’avancement, cela peut réellement être utile. On peut alors construire à la fois un système qui fonctionne et une documentation utile. Mais cela ressemble moins à un document de conception qu’à de la documentation dans le cadre d’un processus continu et collaboratif
Je suis Googler. J’ai aussi publié plusieurs articles de recherche, mais avant je détestais rédiger des documents de conception. Depuis quelques années, j’ai compris les principaux bénéfices que cela m’apporte
Cela me permet de vider de mon esprit la partie immédiate des idées, pour passer à des aspects plus profonds et à des considérations productives
Les défauts deviennent plus visibles, surtout pour moi-même
Il devient plus facile de partager mes réflexions, surtout avec des personnes d’autres bureaux. Elles donnent en général de très bons retours
Cela me permet de bien mieux évaluer la quantité de travail nécessaire que lorsque je me contente de commencer à coder
Cela fait généralement apparaître ce que je dois apprendre avant de coder, comme les systèmes adjacents ou le choix de technologies appropriées
C’est aussi bon pour les promotions, mais les projets réussis le sont encore plus. Comme on me dit souvent que mes documents sont utiles, j’ai l’impression d’avoir trouvé une bonne voie
Est-ce que ça marche vraiment ? Est-ce mieux que les alternatives ? Où est cette discussion ?
Quand je travaillais chez Amazon, la culture des documents de conception était excellente. Mon poste suivant semblait avoir emprunté à la culture d’ingénierie de Google ou à la culture startup typique de SF, et le processus de documents de conception ressemblait à une blague inutile
C’est un mécanisme qui s’inscrit dans une culture de travail plus large. Si vous travaillez seul, c’est un exercice luxueux ; dans une très grande équipe, cela permet de tirer parti de davantage d’expertise dans toute l’équipe et sert aussi de documentation
Il y a plusieurs modes d’échec. Privilégier le livrable plutôt que le résultat est un décalage classique. C’est le cas lorsqu’on écrit un document de 40 pages pour une promotion : sauf dans des cas très juniors où il s’agit de prouver qu’on sait enchaîner des phrases plutôt que faire de l’ingénierie en profondeur, cela marche rarement
C’est aussi excessif pour une équipe qui travaille seule. D’autres petites équipes peuvent communiquer suffisamment avec des tickets, par exemple Jira, et une session séparée pour confronter les idées
Les ingénieurs doivent aussi être onboardés sur la manière de rédiger des documents de conception efficaces. Le commentaire en tête, frustré parce que sa première tentative n’a pas été immédiatement saluée, peut être un signal
Écrire à propos du code est difficile, et HN fait généralement l’éloge de ce genre d’exercice. Si vous travaillez en équipe, méfiez-vous quand vous avez l’impression que votre travail ne consiste toujours qu’en tâches faciles à expliquer dans un document partageable et qui ne nécessitent pas de réflexion approfondie
Si un grand investisseur se faisait passer incognito pour un ingénieur Google pendant quelques semaines, il deviendrait immédiatement un investisseur activiste exigeant le renvoi de Sundar
L’ampleur du potentiel humain gaspillé par la culture des documents de conception de Google est presque impossible à appréhender
La plupart du développement se fait simplement, et parfois on rédige à la hâte un document pour faciliter la justification d’une CL
Dans environ un cas sur dix, je vois quelqu’un en faire beaucoup trop, mais pour l’ingénieur logiciel moyen, ce n’est pas une grande perte de temps
Si je voulais brûler autant d’argent que possible, je concevrais l’entreprise exactement comme cela
La culture des documents de conception a tendance à pousser tout le monde dans une couche de justification de son propre travail. Une culture de la justification est un schéma assez oppressif pour les innovateurs, même lorsque les pairs la renforcent culturellement
Ce système a tendance à empêcher les tentatives visionnaires et les projets ambitieux. Les efforts qui ne sont pas centrés sur le consensus sont réprimés, et le groupe vous punit si vous pensez « hors des normes autorisées »
Ce type de système engendre la pensée de groupe, et son caractère centré sur la tradition du « notre manière de travailler » impose fondamentalement une situation où travailler autrement devient risqué pour la carrière
Dans la Silicon Valley, on trouve toutes sortes de cultures d’entreprise qui s’appuient sur des clichés emballés dans les termes « agile » et « design thinking » ; la plupart relèvent plutôt d’une institutionnalisation qui se fait passer pour « la bonne manière », avec des éléments supplémentaires imposant socialement la variante de culture de culte de l’ingénierie à laquelle ce campus est parvenu
J’ai rencontré un nombre incalculable de personnes, et pas des cas isolés, qui ont quitté Google parce qu’elles estimaient que cela limitait leur carrière, alors même qu’elles y travaillaient très confortablement
Tu as exprimé exactement la frustration que j’y ai vécue. Cela dit, j’aimerais bien retrouver cette rémunération
À propos de l’agile, je l’ai découvert il y a environ 20 ans sous la forme de l’eXtreme Programming, et cela n’avait rien à voir avec le culte du cargo qu’est aujourd’hui SCRUM ou ses imitations
Au fond, c’était un ensemble de principes visant à donner du pouvoir créatif aux développeurs, à empêcher les managers d’interférer avec les méthodes, et à permettre de faire le travail. En revanche, cela donnait au client le droit de dire quoi faire, quand, et dans quelle mesure
Les développeurs estiment eux-mêmes, et le principe est : « ne pas construire ce dont on n’aura pas besoin ». Pas de grosse conception préalable ; le refactoring, les tests, l’architecture et la conception ne sont pas des stories ou tâches séparées, mais font partie de l’overhead continu au titre des bonnes pratiques standard
Les réunions de planning consistent à ce que les collègues se synchronisent dans une salle, et les stories sont exprimées sur des Post-it au tableau blanc avec un minimum de termes non techniques. Le stand-up consiste réellement à ce que les gens se tiennent debout en cercle et donnent une mise à jour très brève, juste assez pour intéresser éventuellement les autres, pas à un rituel pour prouver qu’on est venu travailler aujourd’hui ou pour se mettre en avant
Dans ce système, la conception est une propriété émergente d’un groupe créatif d’experts travaillant ensemble. Cela n’exclut pas les documents de conception et inclut toujours les discussions d’architecture, mais n’exige pas de processus explicite de PRD/document de conception
J’aimerais retravailler dans un endroit comme ça. Google était tout l’inverse, et tout y prenait trop de temps
Ce genre de comportement factice de type « nous sommes très intelligents » est aussi une forme de travail inutile. L’entreprise devrait se concentrer sur des produits qui fonctionnent réellement et se juger là-dessus
Encore un autre Googler
Il y a déjà beaucoup de bons commentaires expliquant que les documents de conception de Google ne servent à rien, mais je voudrais ajouter un autre point de vue sur ce qui me semble poser problème.
Comme cela a été mentionné, les documents de conception servent de dossier de promotion, ce qui génère énormément de superflu. Mais ils semblent aussi se substituer à la vraie documentation.
Tous les documents de conception sont quasiment obsolètes dès qu’ils sont terminés, mais les équipes pointent vers ces documents au lieu d’en rédiger de nouveaux. Résultat : la documentation chez Google est assez mauvaise et datée.
Franchement, il vaudrait bien mieux que le dossier de promotion consiste à écrire un mode d’emploi de deux pages expliquant comment utiliser ce qui existe réellement, plutôt que vingt pages sur « ce qui n’a pas été fait ».
Peut-on voir de vrais documents ? Les documents décrivant les processus de conception logicielle semblent être les secrets les mieux gardés. Je n’ai jamais vu de vrai document utilisable pour une étude de cas.
Kubernetes : https://github.com/kubernetes/enhancements/tree/master/keps
Exemple : https://rfd.shared.oxide.computer/rfd/0177
Index principal : https://rfd.shared.oxide.computer