Créer de la documentation dans un environnement agile
Publié le 6 octobre 2022 par Andrew Owen (8 minutes)
Cherchez sur Google des images de agilité, et vous obtiendrez des concours de chiens. Poursuivons donc cette analogie. Si vous créez du contenu écrit pour des logiciels, le passage de l’approche en cascade à l’approche agile peut vous donner l’impression d’être un chien confronté à l’improviste à une course d’obstacles à l’heure des promenades. Et au lieu d’une fois par jour, les promenades ont lieu toutes les heures. Ce n’est peut-être pas la meilleure analogie. Je ne sais pas quel est l’équivalent pour un chien de devoir jeter tout le travail que vous avez fait la semaine dernière et de recommencer à zéro. D’accord, recommençons.
Agile est une philosophie de développement de logiciels qui se définit par opposition à Waterfall. Selon le manifeste, les valeurs agiles sont les suivantes:
Selon Zed A. Shaw, qui rejette toutes les méthodologies de programmation (il existe même un T-shirt), lorsqu’ils disent qu’ils accordent de la valeur:
Votre expérience de la méthode agile se situera probablement quelque part entre les deux. Dans mon travail, j’ai surtout rencontré la méthodologie de gestion de projet Scrum. Sans entrer dans les détails, vous avez typiquement un cycle de développement de logiciels qui sont mis à la disposition des clients toutes les deux semaines. Cela crée d’énormes maux de tête pour les rédacteurs techniques et les concepteurs d’instructions.
Lorsque Scrum fonctionne, le propriétaire du produit communique les exigences du client, le chef de projet gère l’équipe, le scrum master gère le projet et l’équipe livre quelque chose à la fin d’un sprint de deux semaines. Le sprint commence par une planification visant à déterminer ce qui peut être livré et se termine par une démonstration de ce qui a été créé et une rétrospective de ce qui a fonctionné et de ce qui n’a pas fonctionné. Cette approche signifie que les propriétaires de produits ne peuvent pas simplement dire à l’équipe ce qu’elle doit livrer. Ce qui a conduit à la création du Scaled Agile Framework (SAFe) dans une tentative de reprendre une grande partie de la liberté des développeurs. Mais je m’éloigne du sujet.
Pour le rédacteur technique ou le concepteur pédagogique, la principale différence avec le développement de logiciels en cascade réside dans le fait qu’il s’écoule généralement peu de temps, voire pas du tout, entre l’achèvement du développement d’un logiciel et sa mise à disposition auprès des clients. Cela signifie que vous devez créer votre documentation et vos supports de formation pendant que le logiciel est en cours de développement. Cela signifie que vous devez être prêt à jeter tout votre travail et à recommencer lorsque les choses changent.
L’un des autres objectifs de la méthode agile est de livrer un logiciel qui fonctionne, puis de revenir en arrière et de l’affiner. Cela signifie que votre documentation et vos supports de formation devront être constamment révisés. Cela ressemble à un cauchemar? Oui, c’est un cauchemar. Alors, comment faire face? Du point de vue de la planification, vous devez participer à la réunion de planification au début du sprint. Vous devez être en contact régulier avec le développeur qui travaille sur la fonctionnalité sur laquelle vous écrivez. Vous devez assister à la démo. Vous avez besoin d’un environnement logiciel où vous pouvez tester le logiciel pendant qu’il est en cours de développement.
Vous remarquerez que j’ai parlé de la fonctionnalité (au singulier) sur laquelle vous écrivez. Le plus grand changement dans votre façon de travailler est que vous devez décomposer votre contenu pour qu’il soit aussi atomique que possible. En agile, les fonctionnalités sont typiquement décrites dans une histoire d’utilisateur. Par exemple:
En tant qu’administrateur (rôle), je veux être capable de voir une liste de comptes inactifs (tâche).
Et c’est là le changement de paradigme. Au lieu de décrire le fonctionnement du logiciel, généralement sur la base d’une description exhaustive de l’interface utilisateur, vous décomposez votre contenu en tâches spécifiques à accomplir. L’ancienne méthode aboutissait à des manuels de la taille d’un annuaire téléphonique. La nouvelle méthode signifie que vous devez produire un sujet autonome.
Créée par IBM et gérée par Oasis-Open, la Darwin Information Typing Architecture (DITA) a été à la mode pendant un certain temps dans les cercles de rédaction technique. J’ai toujours trouvé qu’elle était un casse-tête à utiliser, mais elle repose sur un raisonnement solide, notamment le concept de rédaction basée sur les sujets. Au lieu d’écrire un livre entier, vous écrivez un sujet qui peut être l’un des suivants:
tâche - comment faire quelque chose concept - informations descriptives pour définir le contexte d’un sujet référence - informations détaillées, généralement dans un tableau
L’idée est de prendre ces sujets et de les assembler dans des manuels, de l’aide en ligne, etc. En pratique, c’est sur la tâche qu’il faut se concentrer. La rédaction technique et la conception pédagogique ne semblent pas s’être adaptées à l’idée que tous les utilisateurs de leurs logiciels disposent d’une connexion haut débit et savent utiliser Google.
Même si c’est difficile, si vous êtes pressé, vous pouvez faire un lien vers un article de Wikipédia pour obtenir des informations sur un concept. Il en va de même pour les informations de référence générales. Pour les informations spécifiques à un logiciel, vous devrez peut-être créer une rubrique de référence. Mais dans certains cas particuliers, comme les schémas d’API, il est préférable d’avoir un portail interactif dédié aux développeurs plutôt que d’essayer de présenter ces informations dans l’aide en ligne ou les manuels.
Pour le concepteur pédagogique, cela signifie qu’il ne doit pas reproduire le travail de l’équipe de documentation. Les cours doivent pouvoir être liés à des concepts et à des références dans la documentation. Pour cela, il faut que la documentation soit accessible au public ou que la documentation et la formation soient hébergées derrière le même identifiant. Les utilisateurs modernes préfèrent consommer des vidéos plutôt que de lire des manuels, et ces vidéos doivent être courtes. L’idéal est de trois minutes. Quinze minutes est le maximum. Si cela prend plus de temps, essayez de diviser la vidéo en plusieurs sujets connexes.
Si le processus agile se déroule bien, le logiciel changera fréquemment. Cela signifie que les captures d’écran et les vidéos vieilliront rapidement. N’oubliez pas que votre public est intelligent, mais occupé. S’il existe plusieurs façons d’accomplir une tâche, ne leur donnez que la plus simple. Ne leur donnez pas de captures d’écran d’éléments simples de l’interface utilisateur tels que des menus et des boutons. Si vous devez utiliser une capture d’écran, recadrez-la aussi étroitement que possible sur le contenu pertinent. Essayez d’utiliser des descriptions naturelles au lieu d’appels.
En participant au processus de développement, vous avez la possibilité d’influencer le logiciel. J’ai toujours affirmé qu’un logiciel difficile à documenter sera difficile à utiliser. Si vous repérez des problèmes dans l’interface utilisateur, faites-le savoir au développeur. Mais soyez indulgent. Nous devons tous travailler avec des contraintes, et souvent la qualité du travail que nous produisons n’est pas le reflet direct de notre personnalité.
Vient ensuite la réutilisation du contenu. Même s’il permet d’économiser des heures de travail, j’ai rarement vu le single-sourcing bien mis en œuvre. Le texte de base doit être centralisé. Les noms de produits et les éléments de l’interface utilisateur doivent être des variables. La terminologie doit être cohérente d’un produit à l’autre et définie dans un glossaire. Et si vous ne créez pas d’index, vous avez intérêt à disposer d’une excellente fonction de recherche.
Dans l’idéal, vous devez également être en mesure de dériver des données à partir des termes de recherche afin de déterminer le contenu recherché par votre public. Mais même les analyses les plus simples peuvent vous indiquer si le contenu que vous avez créé est consommé. Si vous avez un sujet sur une fonctionnalité que personne ne lit, cela peut signifier plusieurs choses:
Les concepteurs pédagogiques devront abandonner leur approche linéaire traditionnelle du développement de contenu (analyse, conception, développement, mise en œuvre, évaluation). Mais vous avez le choix de la remplacer par quelque chose d’autre:
Je ne suis pas un concepteur pédagogique, je n’ai donc pas de recommandations à faire, je sais simplement que le modèle ADDIE ne fonctionne pas. Je pense que c’est suffisant pour l’instant, mais il se peut que je revienne sur la conception pédagogique agile dans un prochain article.
Image: Original par f/orme Pet Photography.