Écrivez dans un état d'esprit agile
Les méthodologies agiles sont répertoriées au sein d'un manifeste. Bien que le manifeste agile ne fournisse pas de lignes directrices rigides pour l'écriture de documentation en termes de principes agiles, nous pouvons déduire de ses principes et valeurs une méthodologie de documentation qui nous permet d'écrire dans un esprit agile. Le manifeste affirme que les adeptes des principes agiles valorisent :
les individus et les interactions, plus que les processus et les outils ;
un logiciel qui fonctionne, plus qu'une documentation complète ;
la collaboration avec le client, plus que la négociation du contrat ;
la réponse au changement, plus que le suivi d’un plan.
Compte tenu de ces lignes directrices, quelle documentation devons-nous nous attendre à produire pour un projet agile ?
Ces lignes directrices sont axées non seulement sur la livraison d'un produit à un client, mais aussi sur la valeur des actions entreprises pour la réalisation du projet, du point de vue du client. Tout le temps que nous passons sur un projet devrait y ajouter de la valeur, et non servir à s’ennuyer dans des réunions et des activités chronophages, à développer des fonctionnalités inutiles ou à participer à d'autres tâches qui n'ajoutent que peu ou pas de valeur pour le client. Cela vaut aussi bien pour la documentation que pour la programmation.
Revenons à la gestion de projet en cascade (Six Sigma, SDLC, etc.). Dans ce type d'approche, tout se fait par phases, et la documentation est une phase séparée et prédéfinie qui prend une grande partie du temps total prévu au budget du projet. Travailler à partir d'un état d'esprit agile nous force à reconsidérer de telles approches et à réévaluer ce que nous documentons pour déterminer si cela est vraiment nécessaire.
J’ai entendu dire que la documentation était réservée au code, est-ce que c’est vrai ?
Certains pensent qu'avec une approche agile, la documentation ne devrait être réservée qu'au code. Ce n'est pas le cas. Il existe de nombreux éléments de documentation nécessaires pour un projet agile qui ne sont pas liés au code et qui apportent une valeur significative au client.
Documenter avec une mentalité agile signifie que nous n'avons pas besoin de planifier une grande partie de la documentation à l'avance, car nous comprenons que le projet peut changer et changera probablement à mesure qu'il progresse, et nous voulons que notre documentation s’adapte à ces changements. C'est pour cette raison que nous pratiquons la documentation juste à temps. Afin d'éviter de perdre du temps, la documentation d'un projet agile ne devrait se faire que lorsque c'est nécessaire.
Comment puis-je savoir si une documentation est nécessaire ?
C’est LA grande question !
Déterminez quand vous avez besoin de documentation
La documentation juste à temps peut parfois prêter à confusion. Cela ne veut pas dire que nous ne tenons pas compte des besoins futurs du projet, mais simplement que nous ne planifions pas entièrement ces processus au début. Nous décidons quelle documentation devra être produite, et si nous avons une idée de la façon dont les sprints se dérouleront, nous pouvons même identifier quelles pièces appartiendront à quel sprint. En fait, il est important d'avoir une bonne idée de la documentation que vous devez produire avant d'en avoir besoin, mais vous ne voulez pas y consacrer du temps avant d'en avoir besoin.
Ce dont nous avons vraiment besoin, ce sont des conseils ou des lignes directrices pour nous aider à décider quand la documentation est vraiment nécessaire. Voici quelques questions à vous poser pour décider.
A-t-on besoin de la documentation tout de suite ?
Puisque nous pratiquons la planification juste à temps, la documentation va être rédigée en fonction des besoins. Si la documentation que vous envisagez de rédiger s’applique à un sprint ultérieur, attendez ce sprint. Écrivez uniquement la documentation qui s’applique au sprint en cours.
Quel est le public cible ?
S'agit-il d'une personne, d'un service, d'un client ou d'une future équipe de maintenance ? Le fait de savoir cela peut vous aider à décider si écrire de la documentation est approprié, ou s’il vaut mieux utiliser d’autres moyens de communication.
Comment le public cible utilisera-t-il la documentation ?
Est-ce que la documentation sera un outil de référence ou plutôt un manuel de formation ? Identifier la façon dont la documentation sera utilisée vous aidera à décider à quel point elle est réellement primordiale.
Combien cela coûtera-t-il ?
C'est un gros problème. Les coûts peuvent gonfler rapidement, et dans un projet agile, c'est quelque chose que nous essayons tout particulièrement d'éviter. Ainsi, le fait de déterminer le coût de production d'un document, tant en termes d'argent que de ressources, vous aidera à déterminer si vous en avez vraiment besoin. La valeur attendue sera-t-elle supérieure au coût de production ? Si ce n'est pas le cas, vous devriez probablement ne pas écrire la documentation.
Dans la documentation agile, l'objectif est toujours de produire la bonne quantité. Les méthodologies en cascade ont tendance à tout documenter, et c'est tout simplement du gaspillage. Documenter juste ce dont les parties prenantes ont besoin, ni plus ni moins, est votre objectif. C'est comme ceci que vous offrirez la meilleure valeur au client.
Déterminez le quoi, le quand et le où de votre documentation
Nous avons vu comment décider quelle documentation est nécessaire pour un projet. Voyons maintenant à quel moment écrire cette documentation.
Commençons par catégoriser nos besoins en matière de documentation en fonction du temps. Par exemple :
nécessaire avant le début du projet ;
nécessaire pendant le projet ;
nécessaire après la réalisation du projet.
Avoir cette réflexion est un moyen efficace de concentrer vos efforts afin de faciliter la documentation juste à temps.
Contrairement aux approches en cascade, il n'y a pas de phase de documentation spécifiquement prévue dans une approche agile. Ainsi, une catégorisation des besoins large, basée sur cette chronologie simple, facilite la création d'une approche plus fluide de la documentation d'un projet. Les fonctionnalités d'un projet agile sont ajoutées progressivement, avec des changements fréquents. La documentation d'un projet agile doit donc être rédigée de manière incrémentale, afin qu'elle puisse évoluer avec le projet.
Examinons de plus près ces trois échéances.
Avant le projet
Au début d’un projet, très peu de documentation est requise. Rappelez-vous, nous faisons de la documentation juste à temps, et puisque le travail n'a pas vraiment commencé, il n'est pas encore l'heure de documenter.
Pour lancer le projet, il vous suffit de documenter quelques éléments clés :
Quelques diagrammes d'architecture de haut niveau pour identifier les principaux composants de la solution que vous allez implémenter.
Une description des caractéristiques essentielles du produit proposé.
La liste des exigences principales – elles peuvent être de haut niveau ou détaillées, selon la qualité de la définition du projet à ce stade.
Vous n'avez pas besoin de fournir d'informations de conception à ce stade, donc pour l'instant, le but est de définir juste assez d'informations pour que l'équipe puisse démarrer le projet. Très souvent, cette information sera écrite dans le cahier des charges fonctionnel.
Pendant le projet
Pendant que votre produit est en cours de développement, vous produirez probablement deux types de documentation :
Des besoins, minimalistes mais suffisants – ils sont donnés aux développeurs avant chaque sprint.
Une description du système et des processus à l’intérieur du projet – par exemple, les résultats de chaque sprint seront partagés avec les parties prenantes et plus tard avec les équipes de maintenance.
La façon la plus courante de fournir la description prend la forme suivante : « En tant que <acteur>, je veux agir pour apporter une <valeur ajoutée au client>. »
Les critères d'acceptation définissent les termes qui déterminent si la fonctionnalité a été développée correctement et si la user story est terminée. Ils sont rédigés en collaboration avec le client.
Rappelez-vous que dans un projet agile, les user stories ne sont pas des spécifications exhaustives pour une seule activité, mais fournissent plutôt les lignes directrices sur ce que les développeurs sont censés mettre en œuvre.
Après le projet
Tout au long du projet, vous aurez progressivement produit des user stories et des critères d'acceptation, et vos développeurs auront suivi les meilleures pratiques en documentant leur code, de façon à ce que la documentation décrive toutes les fonctionnalités mises en œuvre dans le projet. En d'autres termes, outre les éléments de documentation propres au projet qui pourraient être demandés par les parties prenantes, votre documentation sera en fait complète.
Découvrez le "où" de votre documentation
Puisque la documentation agile évolue avec le projet tout au long du développement, les différents éléments de documentation doivent être des documents vivants. Un document vivant ou dynamique est un document qui est continuellement révisé et mis à jour. Les documents doivent donc être conservés dans un environnement qui supporte des artéfacts vivants.
La documentation de votre projet doit être facilement accessible tout en restant aisément modifiable. La rédaction de votre documentation à l'aide d'un logiciel de traitement de texte standard comme Microsoft Word rend votre documentation statique. Dans un environnement agile, votre documentation doit être traitée de la même manière que votre code source. En règle générale, l'utilisation de plateformes de documents vivants telles que Google Docs ou les wikis de projet sur GitHub sont d'excellentes solutions. Il existe également de nombreuses autres options, y compris l'utilisation d'outils open source pour faciliter la création continue de documents vivants, tels que Cucumber, Concordion, FitNesse, SpecFlow et Pickles.
Il existe de nombreuses façons de gérer votre documentation agile. En fin de compte, c'est à vous de décider d'une solution qui fonctionnera le mieux pour vous, votre équipe et votre projet.
Rédigez une documentation claire
Mais que mettre dans notre documentation ? Passons au quoi !
Rédiger une documentation fonctionnelle efficace est une tâche difficile, mais lire une mauvaise documentation est encore pire. Vous êtes-vous déjà senti plus perdu après avoir lu un manuel d’instructions qu’avant de l’avoir consulté ? C'est douloureux, n'est-ce pas ? Vous ne voulez pas être la personne qui inflige ce genre de douleur aux autres, alors vous voulez vraiment apprendre à écrire une superbe documentation ! J’ai raison, n’est-ce pas ?
Pour vous aider à rédiger une documentation claire et efficace, sans vous enliser dans un million de règles dont vous ne vous souviendrez jamais, vous pouvez suivre une liste de 7 règles présentes dans un excellent article de Bob Reselman, développeur et architecte logiciel.
Les 7 règles de Bob sont :
Divertissez votre lecteur.
Avant de commencer, soyez clair sur ce que vous voulez que votre lecteur fasse une fois que vous aurez terminé.
Écrivez en suivant un plan bien défini.
Évitez les pronoms ambigus.
Clarté = illustrations + mots.
Lorsqu'il s'agit de concepts... illustrez avec des exemples logiques.
Révisez votre documentation.
Que signifient les règles de Bob ?
Divertissez votre lecteur
Nous avons tous été victimes du document austère. Vous commencez à lire, et le temps que vous soyez dans le deuxième paragraphe… Eh bien vous n'êtes jamais arrivé au deuxième paragraphe. Vous en êtes maintenant à votre troisième interprétation de la deuxième phrase du premier paragraphe, et vos yeux deviennent lourds...
Regardons les choses en face. L'écriture ennuyeuse n’est pas faite pour nous. Internet a façonné les humains pour qu’ils veuillent un divertissement constant et une satisfaction immédiate. Et si votre documentation ne peut retenir l'attention de votre lecteur, le Facebook ou Twitter de votre lecteur le fera.
Alors, comment rédiger une documentation de manière à capter et à retenir l'attention de vos lecteurs tout en leur fournissant des informations qui pourraient être vraiment ennuyeuses, mais critiques ?
La façon la plus facile que je connaisse pour divertir un lecteur est d'utiliser la même formule que celle que j'utilise pour divertir une classe, c'est-à-dire pour me divertir. Si je ne m'amuse pas à écrire quelque chose, le lecteur sera probablement ennuyé par ce que je dis. Si je m'ennuie, le lecteur s'ennuiera. Si je suis confus, le lecteur sera confus. Si je ne me soucie pas de ce que j'écris, le lecteur ne se souciera pas de le lire.
Cette première règle est la plus difficile à suivre, car il n'y a pas de règles pour la suivre. Comment savoir si vos lecteurs trouveront votre écriture divertissante ? Comment savez-vous que vos lecteurs ne tournent pas les yeux devant vos tentatives d'être drôle ? (Vous pourriez être en train de lever les yeux au ciel en ce moment.) Je ne peux pas vous dire comment utiliser l'humour, quand l'utiliser ou quand ne pas l'utiliser. Votre propre voix est ce que vous devez cultiver. Oui, c'est ambigu et cette discussion s'est transformée en cours de poésie, mais toute écriture est en quelque sorte créative. Le seul conseil que je peux vous donner, c'est de vous amuser. Si vous aimez écrire votre documentation, votre lecteur ne sera pas tenté d'errer sur les médias sociaux.
Avant de commencer, soyez clair sur ce que vous voulez que votre lecteur fasse une fois que vous aurez terminé
Je sais exactement ce que je voudrais que vous fassiez après avoir lu la première partie de ce cours. Je voudrais que vous passiez le test avec brio ! Lorsque vous rédigez une documentation, on s'attend toujours à une action. En d'autres termes, votre lecteur prend le temps de lire votre document parce qu'il ou elle veut faire quelque chose, et on s'attend à ce que votre document puisse l’aider.
Une très bonne pratique consiste à énoncer l'intention au début du document. Soyez très clair sur ce que vous voulez que votre lecteur fasse après la lecture. Vous en trouverez un exemple dans chaque cours OpenClassrooms. Par exemple, au début de ce cours, vous trouverez la déclaration suivante :
Objectifs pédagogiques
Décrire le rôle d'un cahier des charges fonctionnel.
Analyser un projet pour préparer un cahier des charges fonctionnel.
Créer un cahier des charges fonctionnel.
Il s'agit d'une description assez claire de ce que nous nous attendons à ce que vous puissiez faire une fois le cours terminé. Si vous définissez et énoncez clairement votre objectif final pour le lecteur, il vous sera beaucoup plus facile de rédiger le reste du matériel.
Écrivez en suivant un plan bien défini
Bob, notre ami et auteur des 7 règles, dit : « Rédiger un document sans utiliser un plan, c'est comme essayer de se déplacer dans le métro de New York City sans carte. On peut atterrir n’importe où et ce n'est peut-être pas là où on avait l'intention d'aller. »
Certaines personnes croient que la création d'un plan ne fait que créer du travail en plus. Ce n'est tout simplement pas vrai pour la plupart d'entre nous. Il nous faut une sorte de mécanisme pour nous maintenir sur la bonne voie, et un plan bien conçu peut réduire considérablement votre charge de travail. Dans cet esprit, l'élément clé de cette règle est le terme "bien défini". J'ai écrit sur des plans mal définis et je me suis retrouvé perdu dans ma rédaction en me demandant comment j’étais arrivé là.
Quand vous écrivez à partir d’un plan bien défini, vous savez exactement d'où vous venez et où vous allez.
Éviter les mots ambigus
Je ne suis pas un gourou de la grammaire, mais les mots ambigus me rendent fou, et ils sont trop répandus. Permettez-moi de vous donner un exemple.
Les wombats et leurs écosystèmes sont importants pour nous à Wombat Rescue. Leurs soins et leur bien-être sont au cœur de ce projet.
Avez-vous repéré l'adjectif ambigu ? L'objectif central du projet est-il le soin et le bien-être des wombats, des écosystèmes des wombats ou des deux ? Rien n'est clair à ce sujet. Le soin et le bien-être des wombats sont très différents du soin et du bien-être des écosystèmes des wombats, alors nous avons vraiment besoin de savoir quels soins et quel bien-être nous essayons de dispenser dans ce projet.
Si votre lecteur est confus sur ce que vous essayez de dire parce que vous utilisez des pronoms ambigus, alors votre documentation n’est pas efficace..
Clarté = illustrations + mots
Les illustrations, telles que les graphiques, tableaux, diagrammes ou autres images, devraient améliorer l'efficacité du document, et non l'affaiblir. Votre lecteur n'a pas besoin de perdre son temps à essayer de déchiffrer la signification du graphique étrange que vous avez déposé au milieu de votre document. Votre lecteur a besoin du contexte du graphique pour le comprendre rapidement et éviter toute confusion, et la façon la plus simple d'y parvenir est de mettre une légende.
Une bonne pratique consiste à fournir des légendes numérotées et descriptives pour toutes les illustrations de votre documentation. Assurez-vous de fournir un chiffre ET une légende, pas seulement l'un ou l'autre. Lorsque vous ajoutez des illustrations à votre documentation, assurez-vous de faire référence à l'illustration par la numérotation et l'emplacement (au-dessus ou au-dessous du point de référence) des figures dans votre texte.
Enfin, si vous faites référence à une figure dans votre texte, assurez-vous que votre référence et le numéro de la figure correspondent. Vous ne voulez pas demander à un utilisateur de se référer à la figure 3 ci-dessous, alors que la seule figure sous votre référence est la figure 5. L'exactitude dans l'écriture est une chose merveilleuse.
Lorsqu'il s'agit de concepts... illustrez avec des exemples logiques
Si vous écrivez sur des concepts abstraits, essayez de justifier le concept avec une illustration appropriée et un exemple pour le rendre plus facile à comprendre pour l'utilisateur. La création de telles illustrations et de tels exemples peut s'avérer difficile, mais ils peuvent améliorer considérablement la clarté de votre documentation.
Révisez votre documentation
«La rédaction, c’est 10 % de composition et 90 % de révision ! »
~ Thomas Edison
C'est la dernière règle de Bob. Il est très rare que la documentation soit parfaite au stade de la première ébauche. Bien sûr, puisque nous parlons de documentation agile, nous savons déjà que la première version n'est jamais la seule version. Revoir la documentation est au cœur même de la méthodologie agile. Ne vous souciez donc pas de bien faire les choses du premier coup. Écrivez ce qu'il faut pour que la documentation fasse son travail pour le sprint ou la phase en cours, sachant qu'une révision est à l'horizon.
En résumé
Dans ce chapitre, vous en avez appris beaucoup plus sur les méthodologies agiles et sur la façon dont elles peuvent être utilisées dans la rédaction de documentation technique, notamment :
le but d'une personne utilisant la méthodologie agile est toujours de produire juste assez de documentation. Cela signifie documenter exactement ce dont les parties prenantes ont besoin, ni plus ni moins ;
s'assurer que le temps et les ressources ne sont pas gaspillés à produire des artéfacts inutiles ajoute de la valeur pour le client ;
les documents agiles sont des documents vivants, c'est-à-dire qu'ils sont constamment mis à jour au fur et à mesure qu'ils évoluent avec le projet. Ils nécessitent des environnements vivants. GitHub est un bon point de départ ;
une documentation efficace apporte de la valeur au lecteur lorsqu'elle :
n'ennuie pas le lecteur,
est claire sur ce que le lecteur doit faire après la lecture,
évite les mots ambigus,
utilise des illustrations couplées à des exemples pour plus de clarté,
est facile à réviser.
Le chapitre suivant porte sur les cahiers des charges fonctionnels – ce qu'ils sont, pourquoi nous en avons besoin, comment ils sont utilisés, comment ils s'intègrent dans les méthodologies agiles et pourquoi ils constituent une bien meilleure alternative aux documents de spécification des besoins logiciels (SRS, pour "software requirement specifications," en anglais).
