Cours/Livre/Exemple : comment bien documenter des besoins fonctionnels à destination de développeurs

Allo tout le monde,

J’ai une question qui n’est pas vraiment du dev mais je crois que c’est la catégorie du forum la plus appropriée. N’hésitez pas à déplacer si je me suis perdu :x
Je viens d’être nommé « Product Owner / Analyste Fonctionnel » d’une application web dont ma boite commence le développement. Je suis donc sensé écrire la documentation des besoins fonctionnels à destination de nos développeurs.
Le développement est une nouvelle activité pour ma boite, les développeurs sont nouvellement engagés pour travailler sur ce projet, et personne n’a donc vraiment d’expérience dans le domaine, et écrire de la documentation fonctionnelle pour des développeurs à partir de rien est une nouvelle activité pour moi. J’ai un background technique mais le développement n’est pas vraiment mon domaine.
Et le problème est donc que je nage un peu (beaucoup) et sans formation ni expérience sur le domaine, j’ai beaucoup de mal à formaliser les besoins et même à déterminer par où commencer, ce qui est important de documenter et même sous quelle forme documenter (mockups, schémas de bd, des blocs de texte descriptifs, des workflows?)
J’arrive à leur expliquer à l’oral ce que je veux voir dans l’application mais c’est une autre poutine que de l’écrire et de le formaliser.

J’ai commencé à suivre ce cours-ci : https://www.coursera.org/learn/client-needs-and-software-requirements mais c’est pour le moment plus un survol trop succinct, pas assez pratico-pratique à mon gout.
Alors ma question est la suivante : Avez-vous des bouquins, des cours en ligne, des exemples, n’importe quoi qui puissent m’aider à produire cette documentation pour qu’elle soit intelligible et exploitable pour des développeurs?

Pour donner un peu de contexte, bien que je ne crois pas que ça ait un impact sur la façon de documenter, l’objet du développement est une application web de gestion des horaires/quart de travail qui sera proposée en saas, développée à partir du framework Laravel.

Merci d’avance pour votre aide!
En espérant avoir été suffisamment clair, sur le mien de besoin justement… Si vous avez besoin que je donne plus d’infos pour pouvoir me conseiller, dites-moi :slight_smile:

Ne leur dis pas quoi construire (ou alors seulement apres), commence par decrire les besoins du clients et leur motivations. En detail. Sans rien assumer de ce qui va etre construit pour regler le probleme. Parle du probleme et de pourquoi c’est un probleme. Tu dois expliquer assez pour que tes devs puissent se mettre dans la peau du client.

Chez nous on fait un truc qui parrait zarb au debut. On ecrit un communique de presse (souvent bidon mais pas toujours) qui decrit le produit/fonctionalite qu’on considere construire. C’est litteralementl a premiere chose qu’on ecrit (alors que souvent c’est la derniere chez les autres). Ca permet de bien se placer dans l’optique du client et de vraiment etablir un “vrai nord” directionel pour toute l’equipe, et d’oublier toutes les merdes d’implementation et de contraintes internes. Pour le faire bien il faut savoir jouer le jeu et vraiment se forcer a avoir un truc qu’on pourrait montrer en dehors de la boite et qui serait comprehensible de bout en bout. C’est pas facile.

Ensuite (ecris au meme moment mais qui suit le PR), il y a un doc de 6 pages ou moins (pas plus, c’est important) qui decrit a haut niveau ce qu’on va faire et pourquoi. Encore une fois le but c’est pas de decrire une architecture ou un plan de dev, et en general ca rentre pas dans les details techniques mais ca parle business, business owners, contraintes, vision pour le produit, etapes pour arriver au resultat finat, etc. S’en suit un appendice de ~10 pages avec les questions les plus frequements posees qui viendraient des differentes equipes sur le projet, et qui commence a rentrer dans le details de “mais on va faire ca comment”, et autre “ca veut dire quoi pour X, Y ou Z”. Ca commence a rentrer dans le detail et les challenges. En general le doc d’origine decrit ou on veut aller dans les 6/12 mois et est la pour etablir une vision, le FAQ c’est la ou t’explique comment tu vas te depatouiller du bordel. Les devs seniors et autre doivent etre inclus dans le process pour qu’ils savent ce qui leur arrive dans la figure bientot et pour pas qu’ils viennent te dire a la derniere minute “ouai mais c’est un bordel sans nom impossible a implementer ton truc”.

Dans une equipe de dev tres souvent les decisions techniques sont pas mauvaises dans l’abstrait mais elles manquent juste de contexte. Les gens sont pas deumeures, ils ont juste besoin de tout comprendre comment leur travail a un impact. Au passage ca permet aussi de motiver tes equipes parceque bosser pour implementer un truc que tu piges pas, y a rien de pire. Ton boulot c’est de fournir le contexte pour permettre aux autres de prendre les bonnes decisions. C’est moins facile ou evident qu’il n’y parait…

C’est tout. Apres le reste du detail du pourquoi du comment de l’archi etc a moins que t’ai des dependences pas possibles a resoudre et a gerer des le depart (et dont tu as parle dans le PR/FAQ), c’est laisse aux soins des devs/architectes et ils ecrivent leur propre document technique qui rentre dans le details. Le but pour toi n’est absoluement pas de faire “voila le doc, codez”. C’est “voila le probleme, voila comment pense le client, voila comment on a pense aux etapes, trouvez comment l’implementer du mieux possible dans cet univers”.

9 « J'aime »

Je ne suis pas product owner ou analyste fonctionnel, mais je travaille au quotidien avec en tant qu’ergonome et déjà, ça, ça me pique les yeux. Tu écris une doc fonctionnelle, pas une doc technique (sinon, c’est plus un taf de PO). Pas forcément pour les développeurs donc, mais plutôt pour décrire comment ton projet est censé fonctionner.

Comme l’a dit @GloP, c’est aux personnes qui prennent le relais de l’interpréter correctement et de faire leur taff (ce qui assez facile si c’est fait relativement bien). J’ai envie de dire que ce que toi tu vas faire, n’importe qui doit le comprendre, pas uniquement le développeur.

Et si vous êtes dans une dynamique à priori « agile » (notez les guillemets, merci pas taper), un mockflow détaillé peut sans doute largement suffire pour commencer (Balsamiq et autres outils peuvent bien faire le taf).

Je ne dis pas que c’est la meilleure solution, mais c’est celle qu’on a ici et ça marche plutôt bien. Et si on a des questions, le PO est à nos côtés pour y répondre à tout moment et mettre les choses au point. Pour une petite équipe de 3 ou 4 personnes, ça fait bien le taff.

Vous créez le besoin, ou il existe déjà ?
Parce que dans ce cas, pourquoi ne pas faire une EDB (avec l’aide du métier, interne ou externe) ?

Donc si je comprends bien, vous êtes une boite qui prend un projet pour lequel elle n’a absolument aucune expérience? Pour moi c’est un souci, mais ca veut pas dire que c’est insurmontable.

De mon expérience, ce que tu décris comme façon de procédé dénote d’une mentalité de développement software nommée Waterfall. On définit les besoins en détails, et ensuite on implémente ces besoins pour un livrable “à la fin”.

Le problème c’est que dans le software, souvent, les besoins changent en cours de route (sauf si le client a déjà une application et qu’il faut reprendre les fonctionnalités sans rien changer).

Des techniques de développement plus moderne existent, mais c’est pas sur que ça corresponde à ton client et a votre équipe de développement: les méthodes agiles, par exemple.

Le principe est de fournir des livrables le plus tôt possible, pour avoir des retours clients assez rapidement. Le cycle de développement dure en moyenne de 2 à 3 semaines (chez nous, c’est même passé à la semaine).

Le problème, c’est que le client doit jouer le jeu; si vous avez pas de retours, ça ne sert à rien. Et souvent, le problème est que le client ne joue pas le jeu et se retrouve à dire à la fin “ha non mais ça; ça ne vas pas”. Dans ce cas, tu perds tous les bénéfices d’un cycle de développement court.

Comme l’a dit Glop, commence par:

  • “Vision/Mission-statement” du produit (pour avoir un horizon commun)
  • “User Personas” (qui sont nos utilisateurs?)

Après je conseille une description du MVP (minimum viable product), pour aller a l’essentiel, savoir ce qui est VRAIMENT important a faire en premier.

1 « J'aime »

Chez toi les sprints c’est une semaine ?

Ouais. Mais c’est jusqu’en QA seulement; les test de perfs, preprod et prod sont batchés au bon vouloir des commerciaux. Et du coup, on release qu’un ou deux tickets par semaine.

C’est marrant comme le jargon ressort vite quand on parle de ce qu’on connaît (“QA”, “EDB”, le pauvre s’il ne connait pas vous lui avez fait déjà peur :D).

@Copychat :

Déjà ton rôle… Il faut que ça soit clair, un PO est là pour défendre le client auprès des équipes de dév. Le client ne peut pas être là, ou en tout cas pas tout le temps, il faut quelqu’un qui puisse dire “en tant que client, je veux…” : c’est la base de tout. Et du coup tes spécifications (ou quel que soit le nom que tu donnes à tes documents) peuvent / doivent partir de là : “en tant que client, je veux …”. Autrement dit, tu n’es pas là pour dire aux gens “comment” ils doivent faire, mais “pourquoi”.

Un dialogue bidon autour d’un développement bidon qui explique le périmètre du rôle :

Toi : "Les gars, j’ai formalisé un besoin qui a été exprimé par les utilisateurs."
Ton document : "En tant qu’utilisateur je veux pouvoir ajouter des biloufs dans le popol quand je suis en train de schniffer le grougnon. [blablabla pour expliquer POURQUOI]"
Dév : "Ouais, mais COMMENT on fait ? On rajoute un bouton sur la page qui affiche le bilouf ?"
Toi : "Moi je peux juste te dire POURQUOI on veut ça. Dans mon document j’ai dit que l’utilisateur veut pouvoir ajouter les biloufs dans le popol parce que ça améliore son expérience du schniffage : le grougnon est plus lisible comme ça."
Ergonome : "Ha, alors si on le fait là, il faut que ça soit pour la lisibilité… Dans ce cas le mieux c’est un bouton bien lisible en haut au milieu."
Dev : “En plus on a déjà fait ça il y a six mois sur un autre projet, c’est quelque chose qu’on sait déjà faire ça devrait pas être trop compliqué.” ou "On a jamais fait ça, il faudra probablement nous laisser un peu de temps pour qu’on se renseigne sur la meilleure manière de l’implémenter avant de te donner une estimation du coût."
Toi : “OK, voyez entre vous, et dites-moi d’ici jeudi si c’est faisable, et si oui combien ça coûte. Je verrai si c’est plus rentable pour le client que les autres besoins et je prioriserai en conséquence.

Dans ce cadre là, la nature du document qu’on appelle spécification n’a dans beaucoup de cas aucune réelle importance. Ca peut être un fichier Word, un ticket dans un outil comme JIRA, une page d’un Wiki… Ce qui compte c’est qu’il contienne les élements essentiels :

  • un résumé : “en tant que client je veux…”
  • POURQUOI
  • les critères concrets qui font que la fonctionnalité répond au besoin (exemple : “après l’étape ‘schiffage’, il y a au moins un ‘bilouf’ dans le ‘popol’”)
3 « J'aime »

J’adore ton explication des user stories et de la Definition of done :slight_smile:

J’essaierai de caser tes exemples dans ma prochaine DEF :laughing:

@Copychat

Il faudrait savoir si tu es en organisation Agile ou pas, puisque tu parles de Product Owner. Avec la méthode Agile, on ne parle plus d’écrire une documentation des spécifications fonctionnelles, mais de décrire des User Story, autrement dit récits courts et indépendants des implémentations fonctionnelles attendues.

Mais si tu n’as personne pour cadrer l’organisation, je te souhaite bon courage. Si ta société utilise le cycle en V, ben il faut reprendre les précédentes documents et l’organisation, et si ta société utilise la méthode Agile il faut aussi une structure avec notamment un Scrum master.

Tu peux certes avoir avoir des pré-requis transverses aux méthodes comme ne pas s’avancer sur l’implémentation technique et faire des ateliers pour aller rechercher les expressions de besoins, mais en revanche si tu n’as aucune structure documentaire, ni aucune indications méthodologique (cycle en V, Agile ou autre) ça risque d’être compliqué.

Mais sinon @GloP a fait une très bonne introduction sur le sujet, juste après ton premier message, sans trop s’avancer sur telle ou telle méthodologie, mais en expliquant les bases.

Je suis encore au boulot, donc je prendrai le temps de bien lire vos réponses ce soir,de faire des recherches sur les acronymes, puis de bien vous répondre.
Mais je veux dire merci à tous pour vos réponses déjà, c’est très, très, apprécié.