Kartographe : cartographier un projet, produit et technique

Avant d’engager un chantier sur un logiciel existant, une seule question compte : qu’est-ce que ça touche ?

Passé une certaine taille, personne ne sait y répondre de mémoire. Le produit connaît les parcours, la technique connaît les composants, et le lien entre les deux ne vit que dans la tête de deux ou trois personnes. Ce sont d’ailleurs celles à qui l’on demande toujours, et celles qui partiront un jour.

Kartographe est l’outil que nous avons construit pour ne plus dépendre de cette mémoire — et que nous avons publié en source ouverte.

Le problème, tel qu’il se présente#

Il ne se présente jamais comme un problème de documentation. Il se présente comme un désaccord de chiffrage.

Le dirigeant demande une évolution qui lui paraît mineure. L’équipe annonce trois semaines. Personne ne ment : le demandeur voit un écran, l’équipe voit quatre applications, deux bases et un traitement nocturne. Le désaccord ne porte pas sur l’effort, il porte sur le périmètre — et il n’existe aucun support commun pour en discuter.

La documentation classique n’aide pas. Elle décrit des éléments les uns après les autres, dans des fichiers séparés, écrits à des époques différentes. Elle répond à « comment ça marche ». Elle ne répond jamais à « qu’est-ce que ça touche ».

Ce que Kartographe modélise#

Deux moitiés, et surtout ce qui les relie.

Côté produit. Les personas, les parcours utilisateurs, les scénarios et leurs étapes, avec les assertions qui décrivent ce qui doit être vrai à chaque étape. Et les fonctionnalités, qui regroupent tout cela en unités dont on parle en réunion.

Côté technique. Les applications et leurs contextes délimités, les composants, les routes exposées avec leurs réponses et leurs exemples, les services et leurs actions, les bases de données avec leurs versions, leurs tables, leurs colonnes, leurs contraintes et leurs index, les migrations, les environnements et les versions déployées.

Entre les deux, des liens explicites. C’est là que se trouve toute la valeur. Une étape de scénario pointe vers les routes qu’elle appelle ; une route relève d’un composant ; un composant écrit dans des tables. Le chemin entre « le client valide son panier » et « la colonne statut de la table des commandes » est parcourable dans les deux sens.

C’est ce chemin, et lui seul, qui permet de répondre à la question du départ.

Ce que ça change, concrètement#

Sur un chiffrage. Chaque élément de la carte peut porter une complexité. Un chiffrage cesse alors d’être une intuition globale pour devenir une somme d’estimations attachées à des objets nommés, que l’on peut discuter ligne à ligne. Le client ne conteste plus un total : il conteste une ligne, ce qui est une conversation infiniment plus productive. Nous avions décrit ailleurs pourquoi un bon chiffrage est crucial — c’est l’outil qui manquait pour le tenir.

Sur une reprise de projet. Quand nous héritons d’un logiciel dont l’équipe d’origine n’est plus là, la cartographie est la première semaine de travail. Elle produit ce que personne ne possède : la liste de ce qui existe. C’est le socle de nos audits techniques, et la seule façon honnête d’annoncer un plan.

Sur un arbitrage de gouvernance. Un comité ne peut pas trancher sur un sujet qu’il ne voit pas. Une carte qui montre qu’une fonctionnalité touche trois applications et deux bases dit, sans discours, pourquoi l’estimation est ce qu’elle est. C’est exactement le problème que nous décrivions à propos des conseils qui votent sur des sujets techniques.

Sur un départ. C’est l’usage qu’on n’anticipe jamais. Quand une personne clé s’en va, ce qui manque n’est pas son code — il est là — mais sa carte mentale. La cartographie est la seule partie de ce savoir qui puisse être écrite à l’avance. Nous l’évoquions en décrivant les dix premiers jours après le départ d’un CTO.

Ouvert, et chez vous#

Trois précisions qui comptent, pour un outil censé contenir l’inventaire d’un système d’information.

Le code est ouvert. Le projet est publié sur GitHub selon un modèle open core : le cœur est libre, et l’extension de navigateur qui l’accompagne est diffusée sous licence Apache 2.0.

Il s’héberge chez vous. C’est la propriété la moins spectaculaire et la plus importante. Une carte de projet, c’est la liste de vos applications, de vos routes exposées, de vos tables et de vos environnements — autrement dit précisément ce qu’on ne dépose pas sur un service dont on ignore à quel droit il obéit. Kartographe s’installe sur votre infrastructure, en Europe.

Et il se remplit sans discipline surhumaine. Une extension de navigateur permet de capturer un écran, une adresse ou une étape de parcours pendant qu’on utilise l’application, et de la verser directement dans la carte. C’est exactement ce qui sépare une cartographie qui vit d’une cartographie qu’on met à jour à la main — c’est-à-dire qu’on ne met pas à jour.

L’erreur à ne pas commettre : tout cartographier#

C’est la tentation, et c’est ce qui tue la plupart des initiatives de documentation.

Une carte exhaustive n’est jamais à jour. Une carte qui n’est pas à jour n’est pas fiable. Une carte qui n’est pas fiable n’est plus consultée — et l’on retombe sur la mémoire de deux ou trois personnes, avec en prime un outil de plus à maintenir.

On cartographie ce sur quoi on va décider. Le périmètre d’une refonte. Le domaine d’une reprise. La partie du système qui pose problème. Le reste attend d’avoir une raison d’exister.

Corollaire : une carte reste juste parce qu’on s’en sert. Consultée à chaque chiffrage et à chaque cadrage, elle se corrige d’elle-même — une erreur y saute aux yeux. Constituée pour un audit puis rangée, elle est périmée en quelques semaines.

Deux choix de conception que nous assumons#

La carte porte la discussion, pas seulement la description. Les objets acceptent des commentaires, des réponses, des votes et des complexités. Une décision de conception s’y discute là où elle s’applique, et non dans un fil de messagerie que personne ne retrouvera. Six mois plus tard, la question « pourquoi a-t-on fait comme ça ? » a une réponse localisée.

La carte est lisible par une machine. Elle est accessible à nos assistants par un protocole d’interopérabilité, ce qui leur permet de raisonner sur la structure déclarée du projet plutôt que de l’inférer à partir du code. Cela change la qualité des réponses obtenues — nous avons expliqué pourquoi dans notre article sur ce qui marche vraiment en entreprise. La condition reste la même que pour un humain : si la carte est fausse, la réponse est fausse, et elle est fausse avec assurance.

Ce qu’il faut retenir, même sans notre outil#

L’outil n’est pas le sujet. On peut cartographier un projet dans un tableur, et beaucoup d’équipes le font très bien.

Ce qui compte tient en trois principes :

1. Nommer les éléments avec les mots du métier, produit et technique confondus.
2. Rendre les liens explicites, parce que la valeur est dans les liens et non dans les fiches.
3. Limiter le périmètre à ce sur quoi on décide, pour que la carte reste vraie.

Le jour où quelqu’un demande « qu’est-ce que ça touche ? », la différence entre une équipe qui répond en une heure et une équipe qui répond en une semaine ne tient pas au talent. Elle tient à cela.