Documentation d'intégration : le chemin d'une machine vierge jusqu'à une modification fusionnée

Objectif

Une personne nouvellement arrivée parvient à une première modification fusionnée en suivant uniquement les documents, et les documents s'améliorent à chaque arrivée au lieu de se dégrader entre deux arrivées.

Prérequis

Un README qui répond aux questions de base ; un vivier de petites premières tâches étiquetées ; un propriétaire nommé pour le parcours d'intégration. Le chapitre de Google cité soutient que la plupart des projets méritent un document « Hello World » qui ne suppose rien et amène la personne qui développe à accomplir quelque chose de réel, et que le meilleur moment pour écrire un tel tutoriel est celui où l'on rejoint soi-même une équipe. Diátaxis (cité) classe ce document comme un tutoriel : orienté apprentissage, une activité pratique vers un objectif atteignable.

Étapes

1. Écrire le parcours comme une seule séquence numérotée, avec l'état final énoncé en tête : « à la fin, une modification aura été ouverte, revue et fusionnée ». Tout ce qui ne fait pas partie de ce parcours va ailleurs et y est relié par un lien.
2. Donner chaque étape de mise en place comme une commande exacte avec sa sortie attendue, et un contrôle que la personne nouvellement arrivée peut exécuter (« la suite de tests rapporte N réussites »). Les prérequis (comptes, permissions, matériel) sont listés avant l'étape un, pas découverts à mi-chemin.
3. Fournir une page de repères ne contenant que des liens : dépôts, environnements, qui possède quoi, le glossaire, les canaux de communication, le calendrier des versions. Pas de prose susceptible de se périmer.
4. Indiquer le vivier de premières tâches et l'étiquette qui les marque comme adaptées ; le document explique comment en réclamer une et ce que « terminé » signifie ici.
5. Demander à la personne nouvellement arrivée de tenir un journal de chaque accroc, question et contournement durant les premiers jours, et de transformer ce journal en pull requests sur les documents d'intégration comme premières contributions.
6. Associer au parcours un propriétaire et une date de dernière vérification ; le rejouer depuis une machine propre à l'arrivée d'une nouvelle personne ou à intervalle fixe, et supprimer les étapes qui ne s'appliquent plus. Le chapitre cité décrit des dates de fraîcheur et le marquage des documents obsolètes plutôt que de les laisser en l'état.
7. Conserver une variante pour agent du même parcours : des commandes non interactives, aucune étape exigeant une connexion par navigateur là où un jeton peut être fourni, et une liste explicite des actions que l'agent ne doit pas entreprendre (déployer, supprimer, contacter des personnes).

Résultat attendu

Le temps entre l'arrivée et la première modification fusionnée est borné par le parcours, pas par la disponibilité d'une collègue ou d'un collègue ; les documents d'intégration sont les pages les plus fréquemment corrigées du dépôt.

Limites et base de vérification

Le parcours couvre la mécanique, pas le jugement ; la compréhension du domaine vient encore du travail avec les personnes et des documents de conception. Les environnements qui ne peuvent pas être reproduits sur une machine propre (outils sous licence, données restreintes) ont besoin d'un repli énoncé explicitement. Aucune mesure de temps d'intégration n'est revendiquée.