Votre slack clignote pour la 100ᵉ fois de la journée, plusieurs meetings s'enchaînent autour de thèmes vus et revus et vous sentez qu'il n'y a pas de prise de décisions en perspective.

Et ce n'est pas juste de l'agitation positive, si les équipes n'arrivent à aucune décision, c'est qu'il leur manque une direction plus large. Il y a un problème plus profond : l'absence d'une vision technique claire et partagée.

Si je crois fermement que les "Leads produit" d'une organisation doivent cultiver leur capacité à naviguer dans le flou, c'est-à-dire accepter un changement permanent, c'est bien à eux que revient l'obligation d'apporter de la clarté dans ce flou, une direction, une vision.

Et il y a un outil nécessaire pour ça : l'écrit.

L'importance de l'écrit

Pour ma part, j'écris depuis des années, notamment sur eventuallycoding.com et j'ai par exemple documenté publiquement des prises de décisions historiques :

• notre méthode pour faire des montées de versions de Mongo
• nos raisons de quitter notre PAAS
• le choix de Monit
• le choix d'Ansible

Comme on peut le voir, ce sont des sujets techniques, mais j'ai aussi écrit sur :

• le recrutement en startup
• les risques de Slack

(Cette liste est illustrative, inutile d'aller relire chaque article)

Évidemment il existe aussi tout un tas d'autres documents qui sont restés uniquement au sein de Malt sur les stratégies d'internationalisation, sur les plateformes de paiement, sur notre façon d'aborder notre marché etc.

Ces articles ont permis de constituer un patrimoine, un référentiel auquel se rattacher pour comprendre l'origine de telle ou telle décision, comprendre les compromis du passé et tout simplement la culture, l'état d'esprit au sein de Malt parce que certains articles vont plus loin que l'équipe technique.

Ces articles m'ont permis également de prendre du recul. Quand on écrit on prend du temps pour documenter, sourcer, se former. Ecrire force à clarifier, expliquer, synthétiser.

Dans notre contexte d'équipe distribuée sur plusieurs pays, plusieurs bureaux, c'était également un avantage pour favoriser la discussion asynchrone.

Et si je n'étais pas assez clair jusqu'à présent, je dirais qu'une bonne maîtrise de l'écrit fait partie des critères de maturité d'une équipe technique, et même d'une entreprise.

On retrouve cette culture de l'écrit :

• chez Amazon, qui a développé une forte culture de l'écrit
• chez Square, par exemple via les Hype doc

Mais concentrons-nous ici sur l'usage de l'écrit pour un ou une Senior+ (Staff, principal, etc...).

Ecrire une vision

Pour créer de l'impact, il faut déjà viser quelque part.

Toute personne à partir de Senior doit être capable d'écrire pour articuler document de design, stratégie et vision.

Pour parler de ce sujet, il est difficile de ne pas citer l'excellent livre staffeng.com et le passage notamment sur les stratégies engineering.

Je vais reprendre ici les mêmes définitions pour les types de document dont nous allons parler.

Documents de design

Par document de design, j'entends l'ensemble des documents descriptifs sur un sujet précis. On peut appeler ça ADR, RFC, spécification technique peu importe.

Par exemple :

• notre usage d'openapi en tant que contrat d'interface entre client et serveur
• nos méthodes de sécurisation des appels REST

Ce sont des documents concrets qui décrivent l'usage actuel d'une technologie dans notre contexte.

Documents de stratégies

Ensuite viennent les documents de stratégies. Ces documents peuvent aussi s'exprimer par des RFC, des ADR etc... mais également des roadmaps. Dans tous les cas, une stratégie prend de la hauteur sur les documents de designs. Ce sont des écrits qui sont là pour clarifier, pour donner un guide de conduite par rapport à une technologie.

Par exemple, une stratégie pourrait définir

• "comment nous devons utiliser les apis RESt pour la communication entre micro services"
• ou à l'inverse, "pourquoi nous privilégions la communication par bus de message pour la communication entre micro services"
• "comment et pourquoi nous allons sortir définitivement de mongodb"

Une stratégie est souvent le résultat de discussions contradictoires qui a vu l'équipe s'opposer.

Une stratégie est là pour mettre en lumière les compromis et une décision.

C'est un document qui exprime une opinion, à l'inverse des docs de design qui exprime un état de fait.

Document de vision

Et puis enfin, il est temps de parler de vision long terme.

Le format change ici, on retrouve ce type de document dans :

• des North star document
• des Engineering principles (ou pillars parfois)
• des Manifesto
• des Technology Radar
• des Engineering Blog Posts

Etc... la liste n'est pas exhaustive.

Une vision est là pour montrer une direction à plusieurs années dans le futur.

Par exemple pour reprendre nos exemples ci-dessus :

• quel seront nos patterns de communication intra applications dans 3 ans ?
• comment nous articulerons ces patterns de communication avec un système de monitoring plus optimisé ?
• comment nous allons appliquer le zero trust à notre architecture micro services ?
• dans quelle direction allons-nous orienter notre stack frontend à horizon 3 ans ?

Ici, je présente des sujets techniques, mais une vision peut également porter sur du produit, sur l'usage de l'IA (ou pas), sur l'organisation de l'équipe et de nombreux autres sujets connexes.

Comment démarrer ?

Je suis conscient qu'il est très difficile d'écrire un document de vision quand on ne l'a jamais fait. J'ai mis plusieurs années avant de savoir écrire correctement des documents de stratégies et de vision.

Désormais je décris toujours le même processus, qui rejoint en partie ce qu'écrit Will Larson dans ce chapitre :

• commencer par documenter le passé (document de design)
• résoudre ensuite le présent (matérialiser les conflits dans des documents de stratégies)
• se projeter sur le futur

Et plus concrètement :

• commencer par écrire plusieurs documents de design sur l'existant
• regrouper les documents de design par thème, détecter les questions ouvertes et les contradictions, faire émerger des stratégies
• regrouper les stratégies par thème, projeter les impacts dans le futur

Ce travail n'est évidemment pas solitaire, ni même définitif. C'est un processus collaboratif et itératif. Et c'est aussi ce qui en fait un puissant outil de story telling.

Le story telling

Je fais le lien ici avec un chapitre précédent : l'importance du tech marketing, la capacité à promouvoir et vendre.

Tout l'enjeu d'un ou une senior dans une organisation produit n'est pas uniquement de réaliser une tâche demandée, j'espère que jusqu'ici j'ai été assez clair sur le sujet.

L'enjeu c'est de trouver les problèmes à résoudre et de proposer des solutions.

Mais aucune solution, aucune vision ne s'est jamais imposée d'elle-même. Il faut communiquer, il faut convaincre.

D'autant plus, que, plus vous cherchez à créer un impact large, plus cela va impacter de personnes de l'entreprise. Plus cela va demander du financement.

Les documents mentionnés ci-dessus ne vont pas suffire, mais, s'ils sont bien faits, ils vont vous permettre de créer le storytelling nécessaire pour une bonne promotion, et plus tard pour une bonne conduite de changement.

Ecrits itérativement, ils ont su s'adapter aux objections qui leur ont été fait.

Ecrits collaborativement, ils ont su rallier un ensemble de "champions" qui prendront part à la diffusion des idées.

Et bien sûr s'ils s'appuient sur une base solide d'observations, de compromis et d'écueils (issus des documents de stratégies) et sur tout un tas d'autres éléments que je ne vais pas détailler ici (benchmark, étude quali, et quanti etc...), alors ils ont les bases pour proposer un narratif, un storytelling qui peut s'adresser à tout le monde, technologistes ou non.

Si l'on résume, les documents de design sont comme les "preuves" de votre histoire :

• Ils apportent les détails concrets, les faits
• Ils montrent que vous maîtrisez les aspects techniques
• Ils servent de fondation crédible pour vos arguments

Les documents de stratégie racontent le "comment" :

• Ils expliquent les choix et leurs justifications
• Ils montrent les chemins possibles et celui choisi
• Ils créent la logique de votre narratif

Les documents de vision portent le "pourquoi" :

• Ils donnent le sens, la direction
• Ils créent l'inspiration, l'envie
• Ils permettent à chacun de se projeter

Questions

• Dans les 6 derniers mois, quels documents avez-vous écrits qui sont encore consultés aujourd'hui par vos collègues ?
• Lors de votre dernier changement technique majeur, aviez-vous documenté votre réflexion en amont ? Si oui, comment ce document a-t-il évolué avec les retours de l'équipe ? Si non, quels obstacles avez-vous rencontrés qui auraient pu être anticipés par l'écrit ?
• Documentez-vous les décisions que vous ne prenez pas ? Les compromis qui vous ont amenés à écarter certaines options ?
• Dans votre organisation, quel est le processus pour partager une vision technique ? Si vous deviez proposer un changement majeur d'architecture demain, quel serait votre premier document écrit ?

Ressources

• Ecrire une stratégie engineering
• Tech Marketing
• La culture de l'écrit chez Amazon
• Les Hype docs chez Square