L’Agilité peut faire croire que l’écriture de spécifications est dépassée, c’est faux.
Soyons critique 2 secondes sur la façon dont les méthodes Agiles sont encore vendues à l’entreprise par des mauvais vendeurs: elles évitent l’effet tunnel, elles cassent l’effet Waterfall et donc, grâce à la livraison d’incréments de logiciels réguliers, elles promettent de meilleurs résultats. En effet, il existe des projets qui ne débutent pas avant l’écriture détaillée d’un document fonctionnel, puis d’un document technique. Ensuite ces documents se transforment magiquement en contrat entre le client et le prestataire. Oui là nous sommes en effet sur quelque chose de mauvais. Je peux écrire des heures dessus, mais vous le savez déjà. Une spécification qui ne bouge pas, c’est une photo qui vieillit sur votre écran. Une spécification doit vivre, on va y revenir.
Lorsque j’ai commencé il y a 8 ans à écrire ma première spécification, j’ai eu la chance de travailler avec un bonhomme assez fort sur ce sujet (Fabien si tu es dans la salle, lève la main… ok merci…). Il m’a réellement appris à écrire. Le fonctionnel tout d’abord, qui se concentre sur le « quoi ». Que veux le client ? Que fait-il devant son écran ? Que va faire votre logiciel ?
La spécification technique ensuite, qui explique le « comment » et qui donne aussi les besoins techniques sur les aspects sécurités, déploiement, montée en charge. Bref Fabien lorsqu’il m’a demandé d’écrire ma première spécification, a beaucoup insisté sur la forme, ce qui était antinomique avec mes gènes d’informaticien, intéressé par le fond. Il insistait à l’époque pour que mes documents soient bien présentés. Bien écrire, bien mettre en page, faire des schémas soignés, aérer la mise en page, et surtout : être agréable à lire. Et j’ai compris assez tard que c’était le premier point : soigner la présentation.
A votre avis pourquoi ?
Une spécification n’est pas une notice de médicament de contraception
Si la présentation de votre spécification ressemble à une notice de médicament, une recette de cuisine, ou un disclaimer comme lors de l’installation d’un jeu, ce n’est même pas la peine de prendre le temps d’écrire. Demandez à quelqu’un qui est capable d’écrire. Tout le monde n’est pas fait pour vulgariser, schématiser et délirer à mort dans un document de 305 pages sur l’éplumage automatique des poulets avec le nouveau robot XVW8000-1.
Une spécification doit vivre
Revenons un instant sur les vendeurs de lave-linge de l’Agilité qui vous expliquent que les spécifications créent un effet tunnel. Cette affirmation serait vraie si et seulement si plus personne n’avait le droit de modifier une spécification une fois celle-ci écrite. Est-ce que votre spécification est imprimée dans un livre broché avec couverture quadrichromique ? Non ! C’est un document Word. Et bien puisque vous parlez d’itération tout le temps autour de vous, vous devriez aussi appliquer ce principe à votre spécification technique.
Il est vital d’écrire de nombreuses versions de votre spécification technique ou fonctionnel, et de conserver chaque version précieusement.
Quelques idées pour écrire
Le souci c’est que certains d’entre nous n’ont pas l’option « écrire de la spécification » dans leurs gènes. Prenons ceux qui aiment écrire et qui ont envie de mettre noir-sur-blanc quelques principes et quelques idées. Pour écrire, le plus simple est de penser à un artichaut. D’abord construisez un plan général et complet de votre document. Ensuite commencez par écrire un résumé de 25 lignes au début du document, qui sera lu par 97% des gens qui n’ont pas envie de se plonger dans vos 305 pages sur l’éplumage des poulets avec un robot avec un nom à la con.. On appelle cela un « Executive Summary ».
Ensuite prenez le soin de préciser à quelle audience s’adresse ce document : d’autres développeurs, la MOA, le gars qui fait le ménage le soir sur votre bureau, votre fils qui pourra dessiner au dos de vos pages, etc. Très important. Rien de plus frustrant que de prendre son lecteur par surprise en ne disant pas « Hé sur ce blog on ne parle pas de .NET et d’élevage de fourmis ». Vous suivez ?
Toute couverture de document doit avoir une image. Votre oeuvre de 305 pages doit avoir une image sur la couverture. Je vais vous expliquer pourquoi. En fait, personne ne se souvient d’un document qui s’appelle
« Spécifications Techniques Détaillées pour un outil robotisé d’éplumage des Gallus gallus domesticus,
v 1.2 par Nicolas Martignole »
Par contre si vous mettez une grosse image sur la couverture de votre document, les lecteurs se souviendront de votre document et vous dirons « Où as-tu mis ton document avec la photo du poulet ? »
Pensez à un titre qui soit simple et qui ne soit pas ampoulé. Si vous n’avez pas d’humour, allez acheter des pillules d’humour dans une pharmacie. Vous en prenez 2 le matin et 2 le soir, et vous serez un gars/une fille super marrante dans quelques semaines. Ne pas confondre avec les pilules de l’amour, les bleus. Là vous serez simplement ridicule.
Imaginez : « Spécifications Techniques d’un Robot de découpage des poulets »
Mais tu vas nous dire pourquoi il faudrait écrire ?
Enfin le morceau le plus intéressant. Pourquoi faut-il écrire un minimum avant de débuter un projet ? Tout d’abord parce que les spécifications sont un moyen relativement économique de faire fonctionner votre cortex de communiquant. Ecrire une spécification c’est s’adresser à soit-même avant tout. C’est réfléchir de manière objective sur ce que vous allez faire dans quelques temps. C’est vous forcer à bien capturer les idées de votre client, à préparer un road-book pour les autres développeurs. Une spécification est toujours écrite par une seule personne. J’ai tenté l’écriture à 2, ça ne marche pas tellement. Il faut avoir des relecteurs qui vous corrigeront, mais isolez-vous pour écrire et mettre au propre les explications détaillées de ce que vous pensez réaliser.
Une spécification permet certainement d’éviter un gâchis. Plutôt que d’ouvrir Eclipse et que de commencer à coder sur une idée, un travail en amont d’analyse permet de dégrossir le travail, et donc d’éviter ce temps perdu.
Enfin une spécification n’a pas besoin d’être énorme. La taille ne compte pas. C’est le contenu qui compte. Peut-être que 10 pages avec 3 schémas seront suffisant, qui sait ?
Quel logiciel utiliser ?
Je termine rapidement, en conseillant d’écrire sur un logiciel comme Word ou Pages, afin de soigner la présentation et de préparer un document qui vit car il est imprimé. Oui monsieur, je te dis qu’il faut que tu l’imprimes, pour le lire dans le RER, aux petits-coins, dans la voiture… Bref pour t’en imprégner comme un sachet de thé dans de l’eau chaude.
Oui bon, Google Docs je pense permet de gagner du temps et d’éviter d’abattre des arbres à Fontainebleau pour imprimer ton document. Oui en effet il offre des moyens de collaborations. Donc on peut utiliser Google Docs. Mais pas Emacs, pas LeX, pas un machin d’informaticien qui va produire une notice de médicament.
Enfin pour terminer, prenez le temps de regarder le site Microsoft Office Online qui propose des templates et surtout des images pour illustrer vos documents.
Voilà, qu’en pensez-vous ?
Crédits pour cet article
Cet article est inspiré de réflexions de Joel Splosky sur son blog « Joel on Software« .
Bonjour
Pourquoi ne pas citer openoffice.org qui en plus possède une jolie fonction qui permet de faire à tout moment du versionning de document (du vrai versionning, je ne parle pas de suivi de correction, ce que c’est faire tout logiciel bureautique.)
Et de très facilement mettre à disposition des relecteurs un pdf en un clic.
Je pense que oui il faut des specs, même si les environnements de dev nous facilite tant la tâche qu’on peut très vite avoir un premier résultats et élaborer à partir de ce premier jet. Il faut des specs pour approfondir une idée pour voir plus loin.
Par contre le traitement de texte ne devrait être réservé qu’aux projets obscurs profondément enfouis dans la soute. Dés qu’un projet requiert une interaction utilisateur les specs doivent être faites sous forme de maquettes. Une description textuelle n’aura jamais la puissance descriptive d’une maquette. Un dessin vaut mieux qu’un long discours.
C’est pour ça que je fais mes specs sous Balsamiq et que j’utilise une présentation pour coller le tout ensemble. 1 slide 1 fonctionnalité avec une image et un texte court. Si ça ne tient pas la fonctionnalité est trop compliquée et il faut la découper.
Et pourquoi pas un Wiki pour les spécifications techniques ?
Etant donné que ces specs resteront entre développeurs, un wiki permet de faire évoluer rapidement les spécs avec le code.
Salut Nico,
j’avoue que c’est le 1er billet de ton blog que je ne comprends pas, toi qui est habituellement si clair. Je n’arrive pas à savoir ou tu veux amener le lecteur, et tes arguments ne sont pas (pour moi) trés convaincants.
1. tu commences par critiquer les vendeurs d’agilité soit, mais j’ai du mal à voir la relation avec l’écriture des specs. N’y a t’il que les agilistes qui n’écrivent pas de specs papiers ? (note : l’agilité d’ailleurs ne dit jamais de ne pas écrire de docs, seulement de ne pas oublier que le résultat attendu est du code, pas la doc).
2. ensuite, tu insistes sur la forme. Tout à fait d’accord, une doc intéressante mal présentée ne sera pas lu comme il se doit. Mais tu écris 3 paragraphes pour « conclure » par un « il faut une image et un texte de 25 lignes car personne ne lit les docs ».
3. on continue. L’intérêt de l’écriture de docs ? Se forcer à communiquer les besoins du client de manière claire (mais tout seul hein, faut pas déconner, à 2 ca marche pas). Chez toi, y’a qu’une personne qui voit le client et qui essaye de comprendre ce qu’il faut faire ? Je frémis :).
4. tu finis par la mise en avant de Word, qui est pour moi la meilleure façon de faire n’importe quoi. En phase de réflexion, des outils de mindmaps (ou autre type de graphe), dashboard, post it… permettent de réfléchir bien mieux avec le client ou en interne. Un traitement de texte, c’est fait pour écrire au kilomètre, pas pour réfléchir ou collaborer. Comme dit en commentaire, un wiki est déjà bien meilleur.
Bref, je n’adhère pas du tout à tes arguments. Par contre je partage une idée qui est en filigramme dans ton post : il faut réfléchir avant de commencer à coder tête baissé. Il faut bien discuter avec le client, partager avec les utilisateurs finaux, échanger… et c’est bien plus que faire une doc Word.
Désolé pour ma réponse rapide et surement pas trés construite. Si j’ai pas compris tes propos alors je te devrais une bière au prochain ParisJUG :).
Bon devoxx 🙂
@Seb oui j’aurai dû prendre un peu plus de temps pour l’écrire ce billet. Mais le fond est le suivant : je pense qu’il est important de se poser avant de commencer à coder en écrivant un document.
Par contre là où je n’ai pas été clair (désolé) c’est que pour moi un document c’est 35% de texte, le reste d’images, de diagrammes, d’écrans mockés avec Balsamiq, de mindmaps, etc.
Puisque j’ai lancé l’idée il ne me reste plus qu’à écrire une spécification pour mes robots et à la publier sur le Touilleur Express, histoire d’appuyer mon charabia un peu emballé, qui manque d’explications.
Concernant l’Agilité, j’essayais de dire qu’il est important d’expliquer qu’il est tout à fait possible d’être Agile et d’écrire une spécification, et qu’il est conseillé de se poser avant de se lancer trop rapidement dans un projet.
On en reparle autour d’une biere
A bientot
Nicolas
Hello,
Ton article confirme ce que je pensais, mais beaucoup de questions restent en suspens, j’y reviens par la suite.
Tout d’abord, je plussoie pour dire que Word n’est à mon avis pas la panacée pour les spécifications « itératives ». L’idée du wiki m’intéresse mais je n’ai jamais testé pour l’instant. Cependant, avec ce type d’outil, on se confronte à la difficulté de générer un document papier « propre ».
En ce qui concerne les questions en suspens :
1° Quelle fréquence pour les itérations? Le problème étant qu’à chaque version majeure, il faut faire valider par la MOA qui peut se lasser (et donc perdre de la pertinence dans son intervention).
2° Quel contenu pour les spécs? En scrum, les dévs ont besoin des « user stories » pour commencer un sprint. Est-ce que dans ce cas là, les spécs sont le recueil de ces user stories ou est-ce que l’on doit s’efforcer de décrire des cas d’utilisations de type UML?
3° Comment s’intègre le process de rédaction des spécs avec le projet dans sa globalité?
A moins que je sois complètement à côté de la plaque, je suppose qu’une partie des spécs est rédigée en amont de la phase de développement. Dans ce cas, à quel moment décider que les spécifications sont assez « matures » (?) pour passer aux dévs?
Je rajouterai juste une remarque / expérience:
Attention d’être clair dès le départ dans le « contrat » avec le client, cad tous les interlocuteurs: techniques ET commerciaux ET financiers…) pour dire que la spécification va évoluer de concert avec le dev, les revues, … pour que le produit final soit le plus proche du besoin du client.
Sinon « on » risque de mauvaises surprises genre « Mais dans votre spéc approuvée le … ce n’était pas du tout ce qui était demandé ! ».
Certains décideurs sont très à cheval sur la « spéc » validée lors de la négociation …