Réussir sa documentation logicielle à l’ère DevOps

Les problèmes de la documentation traditionnelle

Une documentation utile et efficace présente trois caractéristiques principales. Elle est :

• complète,
• précise,
• claire.

Avec les approches de développement traditionnelles de type Waterfall, les rédacteurs intervenaient généralement aux derniers stades du projet, avant son lancement. Ils consultaient les notes, les données et les détails des concepteurs et des programmeurs qui avaient terminé – ou presque terminé – le logiciel. Les rédacteurs convertissaient ensuite ces notes, diagrammes, graphiques, menus, descriptions et détails en une documentation achevée et soignée, qui était livrée avec l’application dans sa forme finale, dont la réalisation avait pris des mois, voire des années. Ainsi, la phase de documentation était souvent un effort singulier qui reflétait un produit fini.

Dans le chaos organisé des processus de développement agiles et itératifs, tels que l’approche DevOps, malheureusement, cette méthodologie ne fonctionne plus.

La documentation avec l’approche DevOps

Un projet Agile peut déboucher sur le déploiement d’une première build après quelques semaines, voire quelques jours de développement. La première itération est suivie de releases ultérieures pour corriger les bugs, ajouter des fonctionnalités et apporter d’autres changements ou optimiser les performances. Chaque nouvelle mouture peut apparaître tout aussi rapidement. Chaque version et ses modifications doivent être documentées de manière adéquate pour aider les utilisateurs, les développeurs, les Ops et les chefs d’entreprise.

Ainsi, les exigences de l’approche DevOps mettent une pression énorme sur les rédacteurs techniques, qui doivent fournir et maintenir une documentation de qualité tout au long du cycle de vie du projet. D’autant que ces rédacteurs sont souvent les développeurs eux-mêmes. La pression temporelle des calendriers de livraison DevOps peut se traduire par une documentation de qualité inférieure qui ne répond pas aux qualités énumérées ci-dessus. Voici quelques-uns de ces pièges :

• Les rédacteurs pressés de terminer la documentation peuvent négliger des fonctionnalités – en particulier des éléments secondaires ou de soutien. Si une capacité n’est pas exposée convenablement, les usagers ne sauront pas qu’elle existe ou comment l’utiliser.
• Les descriptions peuvent contenir des informations incorrectes, comme des bévues dans les exemples de codage ou des illustrations inexactes de la syntaxe ou des arguments. Des détails tels que les chemins d’accès aux fichiers ou les noms de variables peuvent être erronés. Et les workflows courants peuvent être représentés de manière imprécise.
• Les éléments décrits peuvent être difficiles à comprendre. L’absence de processus d’édition appropriés permet aux fautes d’orthographe et de ponctuation d’obscurcir le sens d’instructions et de descriptions importantes.

Les problèmes de documentation qui en résultent peuvent ralentir l’adoption d’une nouvelle version ou générer des tickets d’assistance inutiles lorsque les administrateurs tentent de combler les lacunes laissées par un manuel insuffisant ou manquant.

Comment aborder la documentation avec l’approche DevOps

Les entreprises et les équipes logicielles doivent réévaluer la manière dont la documentation du projet est créée et maintenue afin qu’elle reste en phase avec leur cycle de développement.

Appliquez ces quatre changements fondamentaux pour gérer la documentation DevOps.

1. Documentez tôt et souvent.

Alors que la documentation traditionnelle était généralement considérée comme une réflexion après coup ou la touche finale du projet, la documentation DevOps – et, intrinsèquement, ses rédacteurs – doit être intégrée au processus de développement ou au flux de travail dès le début de chaque itération. Cela permet aux auteurs de renseigner, pendant que la construction et les tests sont en cours, la build actuelle, y compris ses caractéristiques, exemples, références, études de cas et autres détails pratiques.

Chaque nouvelle itération doit revoir la documentation existante pour y apporter des modifications et des mises à jour, ainsi qu’ajouter du contenu pour refléter la dernière version. En bref, la documentation doit être placée au même rang que la programmation et les tests.

2. Exigez davantage de connaissances techniques.

Les rédacteurs techniques ne peuvent plus être de simples auteurs. La mise à jour de ce type de contenu dans un environnement DevOps requiert trop de rapidité et d’agilité pour se fier aux notes des architectes et des ingénieurs.

Ils doivent s’approprier le projet et en apprendre les rouages de manière pratique. Cela peut demander des connaissances en programmation, comme la rédaction d’exemples d’API, des compétences en gestion de workflow pour décrire les étapes clés du processus, et des notions en architecture pour présenter le fonctionnement du produit. Actuellement, les recruteurs formulent des attentes techniques accrues avant d’engager les rédacteurs spécialisés.

3. Sollicitez l’aide du personnel technique.

Lorsque des rédacteurs spécialisés sont disponibles au sein du personnel, renforcez les possibilités de communication et de collaboration entre eux et les développeurs. Sinon, les programmeurs et les chefs de projet peuvent élargir leur rôle de rédacteurs techniques pour s’occuper d’au moins une partie du travail. Il peut y avoir plusieurs individus impliqués dans l’effort global de documentation, chacune s’emparant d’une partie de cette tâche.

4. Utilisez des médias alternatifs.

Le temps compte. Les entreprises observent que les formats de documentation traditionnels, tels que les manuels PDF, sont inappropriés, voire impossibles à mettre à jour, dans un environnement de développement Agile. Elles se tournent de plus en plus vers des plateformes plus souples et consultables, plus faciles à créer et à maintenir, comme les wikis. Certains espaces de documentation incluent l’automatisation de l’actualisation du texte en cas de modification du code ou des fonctionnalités. S’il s’agit de s’adresser à une population technique, les fonctionnalités proposées par les fournisseurs de dépôt Git peuvent suffire.

Les meilleures pratiques

Une fois que les entreprises ont adopté des changements pour caler le rythme de la documentation sur leurs projets DevOps, il existe au moins cinq bonnes pratiques à retenir :

1. Éliminer les silos. Les rédacteurs – ou tout autre personnel chargé de la préparation de la documentation – devraient être des membres à part entière et essentiels de chaque équipe de développement, aux côtés des programmeurs. Tout comme une société ayant plusieurs projets simultanés peut partager les développeurs et les testeurs, les rédacteurs peuvent également passer d’une équipe et d’un projet à l’autre pour contribuer à plusieurs efforts.
2. Collaborez. La communication et la collaboration ne sont pas des mots à la mode dans les environnements agiles – elles sont un principe fondateur. Les rédacteurs doivent pouvoir accéder facilement aux notes et échanger librement avec les développeurs et les différentes parties prenantes, selon les besoins, pour élaborer la documentation nécessaire. Cela peut impliquer des réunions d’équipe régulières ou la participation à des processus de test et de validation, par exemple. Plus les rédacteurs en savent sur un produit et son fonctionnement, mieux ils peuvent le documenter.
3. Définissez les exigences en matière de documentation. Chaque projet de logiciel est différent et impose des impératifs de documentation uniques aux équipes de développement et aux rédacteurs. L’on peut spécifier le besoin de références, d’exemples, de cas d’usage, de témoignages d’utilisateurs et de guides pratiques. En établissant des objectifs dès le départ, il est plus facile pour les rédacteurs de les atteindre et de se concentrer sur les types de documentation les plus importants.
4. Adoptez des outils standard. De Microsoft Word aux wikis, il existe un nombre incalculable d’outils et de plateformes qui aident les rédacteurs à créer et à maintenir la documentation. Bien que les outils employés pour la documentation DevOps dépendent des besoins de l’entreprise et du projet, il convient de standardiser un ensemble d’instruments que tous les rédacteurs doivent utiliser. La familiarité avec ces outils spécifiques peut rendre le travail plus rapide et plus efficace.
5. Automatisez les outils lorsque cela est possible. Certains outils de documentation, comme les wikis, possèdent des fonctions qui autorisent l’automatisation de certains aspects du processus de documentation. Par exemple, l’ajout d’un nouvel appel à une API déclenche l’ajout de cet appel à la section de la documentation couvrant les références et les exemples. Cela permet de s’assurer que les rédacteurs étoffent et tiennent compte de tous les changements du code. Lorsque l’automatisation est adoptée, documentez les fonctions d’automatisation et les dépendances afin que d’autres puissent continuer à mettre à jour les outils au fil du temps.

Il n’y a pas de solution unique

Il n’existe pas d’approche standard pour la documentation des projets DevOps ou Agile. Les premières tentatives de normalisation telles que DocOps (open source) n’ont jamais pris racine en raison des nombreuses exceptions et besoins de la documentation logicielle. Les objectifs et les exigences en matière de contenu varient considérablement en fonction du type de projet logiciel, de la portée du projet, de la nature de l’entreprise et des demandes des utilisateurs.

Par exemple, la documentation produite pour un jeu mobile diffère grandement de celle d’une plateforme logicielle industrielle. Les rédacteurs ajoutent toujours de la qualité et de la valeur à un projet logiciel, à condition qu’ils soient capables de suivre le rythme et de relever les défis des environnements agiles.