Ne mettez pas vos spécifications dans Jira

Quand on est PO on est tellement absorbé par la conduite du projet, qu’en général on ne prend pas le temps de se concentrer sur les outils et les pratiques qui permettent de s’en sortir. Je parle souvent de l’importance d’apprendre à toujours mieux découper ses stories, mais ici je vais vous parler de documentation : pourquoi ça fait gagner du temps et comment faire ça très facilement.

La doc c’est bien …

Tout le monde est d’accord pour dire que la documentation c’est bien, mais la définition n’est pas la même pour tout le monde. La documentation, c’est l’ensemble des documents (!) qui permettent de rentrer dans le projet et de faciliter la réalisation des features à venir.

Rentrer dans le projet

L’arrivée d’un nouveau membre dans une équipe existante est toujours un moment de pression, et pour l’arrivant, qui est jugé sur sa rapidité à s’intégrer et à délivrer, et pour le reste de l’équipe, qui doit faire un effort supplémentaire pour transmettre les informations et le mettre vite à niveau.

Dans ce cas là, la documentation doit permettre de présenter de manière claire l’environnement (technique, outils, pratiques, équipe, dépendances), les objectifs haut niveau, les grands domaines fonctionnels, la stratégie suivie actuellement, la roadmap.

Plutôt que de se fier à la tradition orale, une documentation maintenue permet d'accélérer l’onboarding et d’éviter de perdre l’onboardé.

Une bonne pratique est de profiter de chaque nouvelle arrivée pour mettre à jour ces documents.

Faciliter la réalisation

C’est important de faire la différence entre documentation et spécification : la spec sert à faire, la doc sert à comprendre.

Quand on écrit une user story (spécification) il y a une partie sur ce qui doit être fait, et une partie sur le contexte : d’où on part, quelle est la réalité technique, pourquoi on veut changer, à quoi il faut faire attention etc.

Il y a un mécanisme qui est facile à observer : plus l’équipe connaît le contexte, moins le product owner doit le détailler dans la spec. En général, ce contexte est dans la tête des membre de l’équipe, et il se transmet par l’expérience et l’immersion.

Le problème est évident et récurrent : si le contexte est implicite, il n’est pas réécrit dans la spec, et si un membre de l’équipe n’a pas le contexte en tête, un élément sera oublié pendant la réalisation.

Pour éviter ces problèmes, il y a deux solutions : soit le PO décrit en détail tous les éléments du contexte à chaque user story, soit on maintient une documentation à jour.

… Mais on a pas le temps !

On ne va pas se mentir : rares sont les product owners qui ont le temps de faire toutes les tâches liées à leur poste, et la documentation va être un des éléments qui va passer à la trappe en premier.

Pourtant une bonne partie des tâches chronophages peuvent être réduites grâce à la documentation : la gestion des bugs et des retours, l’écriture des spécification, l’analyse de l’existant, la gestion des dépendances inter-équipes, etc..

Donc il est possible, si on s’y prend bien, d’avoir un ROI positif sur le temps passé à écrire la documentation.

A priori, ça paraît illusoire, car on imagine la documentation comme une montagne de travail, une corvée qui n’en vaut pas le coup. Il y a deux raisons majeures à ça : on a en général pas la bonne approche, ni le bon outillage.

On a la mauvaise approche parce qu’on voit la doc comme un travail séparé de la spec, mais qui demande un effort équivalent. Et effectivement, si on doit réécrire les mêmes informations, avec le même niveau de détail, dans deux endroits différents, l’effort est trop important.

Mais en réalité, le gros du travail est déjà fait avec l’écriture des user stories, des suites de tests, des documents de démo et des livrables pour les autres services. L’enjeu de la doc n’est plus “comment retranscrire l’ensemble des informations dans ce nouveau document ?” mais bien “comment tirer partie de l’existant pour donner du sens et un lien entre les éléments ?”.

La faute à JIRA

L’intérêt d’un outil de gestion de tickets comme Jira tient dans la représentation du flux et l’exploitation des méta données : on veut s’organiser autour du travail et on veut mesurer notre efficacité.

Mettre les spécifications dans Jira revient à les mettre à la poubelle. C’est lié au principe même de la découpe en user stories : c’est une découpe arbitraire et temporaire, qui n’a de sens qu’au moment de l'exécution. Imaginez une goutte d’eau qui tombe dans un verre. Pendant le trajet la goutte existe, mais une fois dans le verre, la distinction avec le reste de l’eau n’a plus de sens. En mettant les spécifications dans Jira, on maintient artificiellement leur statut de goutte d’eau, sans avoir la possibilité de les rassembler.

Bien sûr, chacun s’organise comme il peut, avec des règles de nommage de ticket, avec des catégories, des tags, des epics etc. Mais il y a un test très simple à effectuer : choisissez une page importante de votre application qui date un peu et demandez à une personne en dehors de l’équipe de retrouver dans votre Jira l’ensemble des règles de gestion de cette page. Il y a très peu de chance que ça marche. Et ce problème vous le rencontrerez à chaque changement dans l’équipe.

Comme Jira n’est pas fait pour être une base documentaire, c’est normal que ça soit difficile de s’en servir pour ça. Mais si on ne peut pas se servir des specs pour faire la doc, alors la doc passe à la trappe.

L’arborescence et le Wiki

Aujourd’hui, la meilleure façon que je connaisse de se sortir de tout ça facilement, c’est d’utiliser un wiki et de s’appuyer sur une arborescence. Si vous avez Jira, vous avez forcément Confluence, et vous pourrez en plus tirer partie de l’intégration entre les deux.

On attache les user stories à leur features, et les features sont organisées par domaine. Ça rend facile d’avoir une vision globale et de naviguer dans la documentation.

L’idée principale est de mettre le contenu de la user story dans sa propre page wiki. Ensuite on met le lien de cette page dans le ticket de Jira. Ça ne change rien pour l’organisation du travail, mais avec ce peu d’effort, on gagne énormément à la réalisation : quand on travaille sur une user story, on aura toutes les infos nécessaires sur une seule page (la spécification), mais si on veut plus de contexte, on peut remonter aux informations de la feature et voir facilement les user stories qui ont déjà été réalisées (la documentation).

Le travail de documentation est aussi facilité, parce qu’il se fait au fur et à mesure. A chaque fin de sprint, on peut se prendre une heure pour remonter les informations importantes des user stories réalisées vers leurs pages features.

Chaque page Feature va contenir les intentions et les objectifs de la feature, des captures d’écran, un récapitulatif des règles importantes etc.. Les pages Domaine vont donner du sens plus global et long terme : le contexte général et les objectifs au niveau produit.

Donc pour faire facilement une documentation utile, il suffit de ne pas mettre ses specs dans Jira.

---

Bonus : bonnes pratiques d’une documentation wiki

Vous allez passer du temps sur cette documentation, alors chaque élément qui peut faciliter les choses vaut le coup. Donc voici quelques bonnes pratiques qui m’ont fait gagner du temps :

Création

J’ai l’habitude de créer une page dès que je commence à travailler sur une feature ou une user story. Je m’en sers pendant le processus de création, j’y attache les documents de travail comme les comptes rendus de réunion ou les maquettes. Ces informations servent à enrichir la documentation sans trop me fatiguer.

Stock

Par contre, le risque c’est d’avoir des pages dans notre arborescence qui correspondent à des features ou des US qui n’ont pas été réalisées ou qui ne le seront jamais. Pour pallier à ça, je crée mes pages brouillons dans un dossier à part, et je ne les ajoute dans l’arborescence principale qu’au moment de la réalisation. Il faut faire attention aussi à sortir les user stories ou features qui n’ont pas pu être développées dans un sprint et qui sont dépriorisées.

Templates

Ça parait évident, mais l’utilisation des templates change la donne. Ça permet de se guider dans la production des documents, de s’assurer que tout est lisible et qu’on n’a rien oublié. En m’appuyant sur les revues de specs et les ateliers definition of ready je fais évoluer mes templates au fil du projet, c’est un très bon axe d’amélioration continue.

Migration

Quand on a un existant dans Jira et qu’on souhaite faire la migration, je conseille d’en faire une tâche dans un sprint. C’est un travail d’équipe qui prendra plusieurs jours. Le bon côté c’est qu’en repassant sur toutes les vieilles specs, on redécouvre des informations, on fait émerger des nouveaux axes d’amélioration et tout le monde comprends mieux le produit.

Mise à jour

C’est important de ritualiser les mises à jour de la documentation. Il ne faut surtout pas se créer une pile de travail, parce que ça passera systématiquement à la trappe et ça en sera fini de notre doc. Donc à chaque fin de sprint, je me prend une heure pour repasser sur ce qui vient d’avoir été modifié. Je vais remonter les informations clés des US dans les pages features, m’assurer que les captures d’écrans sont à jour, attacher les documents que j’ai produit pour les différentes réunions et démos, etc..

Page dépréciée

Un autre élément à prendre en compte en fin de sprint est la dépréciation des vieilles user stories. Régulièrement, un nouveau développement va annuler et remplacer un ancien. Ça vaut le coup de garder les vieilles specs, mais de bien marquer qu’elles sont obsolètes.

Doc technique

Il faut aussi encourager l’équipe de dev dans la production de doc technique pour les parties complexes. L’organisation en arborescence rend facile d’y ajouter leurs pages et documents. C’est très pratique de commencer un développement sur une nouvelle US et d’avoir facilement accessible le contexte de la feature, les autres us et la doc technique liée à cette feature.

Cette doc technique doit aussi être maintenue, donc c’est une bonne idée pour les devs de repasser rapidement dessus en fin de sprint.

Suites de tests

Toujours dans l’optique d’avoir toutes les informations au même endroit, je vais toujours faire en sorte d’attacher ou de mettre un lien dans chaque page feature vers leurs suites de tests respectives.

Commentaires

Et c’est pareil pour les commentaires. Si vous regardez n’importe quelle US dans un ticket Jira, vous retrouverez des informations fonctionnelles ou techniques importantes dans les commentaires. Ça serait dommage de les perdre. Donc j’essaye de faire en sorte que les commentaires soient écrits sur la page US dans le wiki plutôt que sur le ticket.

Outils externes

Enfin, il faut faire attention aux liens vers des outils externes. Par exemple un lien dans l’US vers la maquette designée dans l’outil du designer. La plupart du temps, quelque mois plus tard, la maquette a disparue et on a perdu l’information. Donc pour chaque type d’outil externe il faudra se poser la question de la pertinence de sauver l’information ou non.