Les spécifications fonctionnelles sans peine - 4ième partie: Petits conseils

From The Joel on Software Translation Project

Revision as of 14:54, 23 September 2006 by Alan71 (Talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search
Article original: Painless Functional Specifications - Part 4: Tips
Date de publication: 15 octobre 2000
Traducteur: Benoit Brodard
Vérifié par: Non-communiqué
Navigation: Retour à Main Page Retour à French FrenchFlag.png




Bien, nous avons vu pourquoi vous avez besoin de specs, ce que contient une spec, et qui doit les rédiger. Dans cette quatrième et dernière partie de la série, je partagerai avec vous quelques uns de mes conseils pour rédiger de bonnes specs.

Le plus grande reproche que vous entendrez des équipes qui effectivement écrivent des specs est que "personne ne les lit". Quand personne ne lit les specs, les personnes qui les rédigent ont tendance à verser dans le cynisme. Cela ressemble au bon vieux dessin de Dilbert dans lequel les ingénieurs utilisent des spécifications de 10 cm d'épaisseur pour surélever les cloisons de leur espace de travail. Dans votre grosse entreprise typiquement bureaucratique, tout le monde passe des mois et des mois à écrire des specs inintéressantes. Lorsqu'une spec est terminée, elle atterrit sur une étagère et n'en redescend plus jamais, et le produit est implémenté de zéro sans se soucier de ce que dit la spec; elle était si abrutissante. Le processus même d'écrire la spec aura peut-être été malgré tout un bon exercice car il aura au moins forcé chacun à réfléchir aux problèmes possibles. Mais le fait que la spec ait été empilée dans un coin (non lue et rejetée) une fois terminée conduit tout le monde à penser qu'il s'agissait d'un gros travail pour rien.

Egalement, si vos specs ne sont jamais lues, vous vous retrouvez avec tout un tas de conflits lorsque le produit final est livré. Quelqu'un (du management, du marketing, ou un client) dit: "attendez une minute ! Vous aviez promis qu'il y aurait un Panier à Vapeur ! Où est le panier à vapeur?" Et le programmeur répond, "non, en fait, si vous regardez les specs chapitre 3, sous chapitre 4, paragraphe 2.3.0.1, vous verrez qu'il est dit de manière assez explicite 'pas de panier à vapeur.'" Mais cela ne satisfait pas le client, qui a toujours raison, et donc les grognons de programmeurs n'ont plus qu'à réintégrer un panier à vapeur dans la chose (les rendant encore plus cyniques concernant les specs). Sinon un manager dit, "oh, tout le texte de cette fenêtre de dialogue est trop verbeux, et il devrait y avoir un avertissement en haut de chaque boîte de dialogue." Et les programmeurs répondent, frustrés, "mais vous avez approuvé les specs qui indiquaient précisément le format et le contenu de chaque boîte de dialogue!" Mais naturellement, le manager n'avait pas réellement lu la spec, parce que lorsqu'il a essayé, son cerveau lui est sorti par les orbites, et de toute façon, cela interférait avec son golf du mardi.

Donc. Les specs c'est bien, mais pas si personne ne les lit. En tant que rédacteur de specs, vous devez amener les gens à lire vos specs, comme dans un piège, et vous devriez certainement faire un effort pour ne pas forcer des cerveaux déjà trop étroits à sortir par les orbites.

Piéger les gens à lire votre truc est juste habituellement une question de rédaction décente. Mais ce n'est pas fairplay de ma part de dire simplement "soyez un rédacteur décent" et d'en rester là. Voici quatre règles simples que vous devez absolument suivre pour réaliser des specs qui soient lues.

Contents

Règle 1: Soyez drôles

Ouais, la règle numéro un pour piéger les gens à lire vos specs est de rendre l'expérience agréable. Ne me dites pas que vous n'êtes pas nés drôle, je n'y crois pas. Chacun de nous a des idées drôles en permanence, mais se censure parce qu'il pense que ce n'est pas "professionnel". Pfiou... De temps à autres, les règles sont faites pour être violées.

Si vous lisez les tas d'insanités que j'ai écrits sur ce site web, vous remarquerez qu'il y a quelques basses tentatives d'être drôle éparpillées ici et là. Il y a quatre paragraphes de cela, je faisais une grossière plaisanterie et me moquaient des managers qui jouent au golf. Bien que je ne sois pas si drôle que ça, j'essaye avec obstination, et même le fait d'aller d'ici de là essayer d'être drôle est distrayant en soi, à la manière d'un clown triste. Quand vous rédigez une spec, les exemples constituent une bonne place pour être drôle. Chaque fois que vous devez raconter une histoire sur une fonctionnalité, au lieu de dire:

  • L'utilisateur entre Ctrl+N pour créer un nouvelle table Employés et commence à entrer le nom des employés..

écrivez quelque chose comme:

  • Miss Peggy, tapant sur son clavier avec un crayon à cils parce que ses petits doigts boudinés sont trop gros pour presser les touches individuellement, tape Ctrl+N pour créer une nouvelle table "Petits Copains" et saisit le seul enregistrement "Kermit."

Si vous lisez beaucoup Dave Barry, vous découvrirez qu'une des manières les plus drôles d'être drôle est d'être précis quand ce n'est pas nécessaire. Des "roquets hargneux" sont plus drôles que des "chiens". "Miss Peggy" est plus drôle que "l'utilisateur". Au lieu de dire "intérêts particuliers," parlez des "cultivateurs d'avocats gauchers." Au lieu de dire "Les gens qui refusent de nettoyer derrière leur chien devraient être punis," dites qu'il devraient être "envoyés dans des prisons si isolées que les prisonniers doivent payer les araignées pour une passe."

Oh, et, au passage, si vous pensez que ce n'est pas professionnel d'être drôle, alors, je suis désolé, mais vous n'avez vraiment pas le sens de l'humour. (Ne le niez pas, les gens sans sens de l'humour le nient toujours. Vous ne pouvez pas me tromper.) Et si vous travaillez dans une société où les gens vous respecterons moins parce que vos specs sont légères, drôles, et agréables à lire, alors, aller trouver une autre société pour laquelle travailler, parce que la vie est vraiment trop courte pour passer vos heures de la journée dans un endroit si sombre et misérable.

Règle 2: Rédiger une spec ressemble à écrire du code executable par le cerveau

Voilà pourquoi je pense que les programmeurs ont des soucis à écrire de bonnes specs.

Lorsque vous écrivez du code, votre principale audience est le compilateur. Ouais, je sais, des personnes aussi ont à lire le code, mais c'est généralement très difficile pour elles. Pour la plupart des programmeurs, c'est déjà assez difficile d'obtenir un code qui soit lisible et correctement interprétable par le compilateur; s'inquiéter d'écrire un code lisible humainement est un luxe. Que vous écriviez:

void print_count( FILE* a, char * b, int c ){
fprintf(a, "il y a %d %s\n", c, b);}

main(){ int n; n =
10; print_count(stdout, "employés", n); /* code délibérément complexe */ }

ou

printf("il y a 10 employés\n");

vous obtenez le même résultat. Voilà pourquoi, quand vous y réfléchissez, vous allez avoir pas mal de programmeurs qui écrivent des choses du genre:

Supposons une fonction AdresseDe(x) qui est définie comme la correspondance d'un utilisateur avec l'adresse email conforme à la RFC 822 de cet utilisateur, une chaîne ANSI. Prenons un utilisateur A et un utilisateur B, où A veut envoyer un email à B. Donc A initie un nouveau message en utilisant une (mais pas toutes) des techniques définies ailleurs, et entre AdresseDe(B) dans la boite de dialogue "à:".

Cela aurait pu être ainsi spécifié:

Miss Peggy souhaite aller déjeuner, elle crée donc un nouvel email et saisit l'adresse de Kermit dans la boîte "à:".

Note technique: l'adresse doit être une adresse Internet standard (conforme à la RFC 822).

Les deux "signifient" la même chose, en théorie, mis à part que le premier exemple est incompréhensible à moins que vous le décodiez avec attention, tandis que le second est d'une approche aisée. Les programmeurs ont souvent tendance à rédiger des specs qui ressemble à de denses rapports universitaires. Ils pense qu'une spec "décente" doit être "techniquement" exacte et ils sont à côté de la plaque.

L'erreur réside dans le fait que lorsque vous rédigez une spec, en plus d'être correcte, elle doit être compréhensible, ce qui, en terme de programmation, signifie qu'elle doit être écrite pour que le cerveau humain puisse la "compiler". Une des grandes différences entre les ordinateurs et le cerveau humain est que les ordinateurs ne rechignent pas à attendre patiemment tandis que vous définissez des variables que vous voudrez bien utiliser plus tard. Mais un humain ne comprendra pas ce dont vous parlez à moins que vous le motiviez en premier lieu. Un humain ne veut pas avoir à décoder quoi que ce soit, il souhaite juste lire la spec dans le bon sens et la comprendre. Pour un humain, vous devez fournir l'idée générale et ensuite apporter les détails. Avec un programme, vous commencez du début jusqu'à la fin, avec une foule de détails entre les deux. Un ordinateur ne s'inquiète pas si vos noms de variable n'ont pas de sens. L'esprit humain comprend beaucoup mieux les choses si vous pouvez dépeindre un tableau vivant à travers une histoire, même s'il s'agit seulement d'un fragment d'histoire, parce que nos cerveaux ont évolué pour comprendre des histoires.

Si vous montrez un échiquier, en plein milieu d'une vraie partie d'échecs, à un joueur expérimenté, le temps seulement d'une seconde ou deux, il sera instantanément capable de mémoriser la position de chaque pièce. Mais si vous bougez deux ou trois pièces dans des directions qui n'auraient pas de sens dans une partie réelle, (par exemple, placez des pions sur la première rangée, ou placez les deux fous noirs sur des cases noires), il devient beaucoup, beaucoup plus difficile pour lui de mémoriser le jeu. C'est très différent de la façon de penser des ordinateurs. Un ordinateur qui pourrait mémoriser un jeu d'échec pourrait mémoriser aussi aisément une configuration réaliste et une configuration impossible. La manière dont le cerveau humain fonctionne n'est pas aléatoire; les chemins de pensée ont tendance à se rigidifier dans notre cerveau, et certaines choses sont vraiment plus simples que d'autres à concevoir parce qu'elles sont plus coûtumières.

Donc, lorsque vous rédigez une spec, essayez d'imaginer la personne à laquelle vous vous adressez, et essayer d'imaginer ce que vous lui demander de comprendre à chaque étape. Phrase par phrase, demandez vous si la personne qui la lit la comprendra en profondeur, dans le contexte de ce que vous avez déjà dit. Si certaines personnes de votre audience ne connaissent pas la RFC 822, vous devez la définir, ou, au minimum, la dissimuler dans une note technique pour que les responsables qui liront la spec n'abandonnent pas et n'interrompent pas leur lecture dès les premiers termes techniques.

Règle 3: Ecrivez aussi simplement que possible

N'utilisez pas un language empoulé et formel sous prétexte qu'il ne serait pas professionel d'écrire des phrases simples. Utilisez le langage le plus simple que vous pouvez.

Les gens utilisent des mots comme "complexe" parce qu'ils pensent que "compliqué" n'est pas professionel. (A nouveau ce mot "professionel". Chaque fois que quelqu'un vous dit que vous ne devriez pas faire quelque chose parce que ce n'est pas "professionel", vous savez que cette personne est à cours d'arguments réels.) En fait, je pense que de nombreuses personnes imaginent qu'une rédaction claire indique que quelque chose ne va pas.

Décomposez les choses en phrases brèves. Si vous n'arrivez pas à écrire une phrase claire, coupez la en deux ou trois phrases plus courtes.

Evitez les murs de texte: des pages entières pleines de texte. Les gens s'effraient et ne les lisent pas. Quand avez-vous noté pour la dernière fois un magazine populaire ou un journal avec des pages entières de texte? Les magazines iront jusqu'à prendre une citation de l'article et l'imprimer, au milieu de le page, avec une police géante, à seule fin d'éviter l'apparence d'une pleine page de texte. Utilisez des listes numérotées, énumérées, des images, des graphiques, des tables, et beaucoups d'espaces pour que la lecture soit plus "aérée".



"Les magazines iront jusqu'à prendre une citation de l'article et l'imprimer, au milieu de la page, dans avec une police géante, à seule fin d'éviter l'apparence d'une pleine page de texte."


Rien n'améliore plus une spec que des captures d'écran et encore des captures d'écran. Une image peut valoir des milliers de mots. Quiconque écrit des specs pour Windows devrait investir dans un exemplaire de Visual Basic, et apprendre à l'utiliser au minimum assez bien pour réaliser des maquettes. (Pour Mac, utilisez REAL Basic; pour des pages Web, utilisez FrontPage ou Dreamweaver). Capturez ces écrans, (Ctrl+PrtSc) et collez les dans votre spec.

Règle 4: Repassez sur vos specs et relisez les plusieurs fois

Hum, bien, j'avais tout d'abord prévu d'avoir une longue exégèse de cette règle ici, mais elle est vraiment trop simple et trop évidente. Repassez sur vos specs et relisez les plusieurs fois, d'accord ? Si vous trouvez une phrase qui ne soit pas super facile à comprendre, réécrivez la.

J'ai économisé tant de temps en n'expliquant pas la règle 4 que je vais en ajouter une autre.

Règle 5: Les modèles, considérés comme dangereux

Evitez de succomber à la tentation d'écrire un modèle de specs. Au départ, il se peut que vous pensiez simplement qu'il est important que "toutes les specs se ressemblent". Indice: ça ne l'est pas. Quelle différence cela ferait-il ? Est-ce que tout les livres de votre bibliothèque chez vous se ressemblent ? Vous le souhaiteriez ?

Pire, si vous avez des modèles, ce qui finit par arriver est que vous ajoutez un tas de sections au modèle pour les choses qui sont importantes pour chaque fonctionnalité. Par exemple : Grand Bill décide qu'à partir de maintenant, chaque produit Microtruc doit avoir un module Internet. Donc le modèle de spec à maintenant une section intitulée "Module Internet". Dès que quelqu'un écrit une spec, aussi triviale soit-elle, il doit remplir une section intitulée "Module Internet", même s'il doit juste rédiger la spec pour le clavier Microtruc. (Et vous vous demandiez pourquoi ces touches de navigation Internet ont commencé à pululer comme des champignons sur les claviers).

Tandis que ces sections s'accumulent, les modèles deviennent assez gimposants. (Voici un exemple d'un très, très mauvais modèle de specs. Qui a besoin d'une bibliographie dans une spec, pour l'amour du ciel ? Ou d'un glossaire?) Le problème avec un modèle si imposant, c'est qu'il effraie les gens d'écrire des specs. Cela semble une tâche par trop énorme.

Une spec est un document que vous voulez que les gens lisent. Dans ce sens, ce n'est pas différent d'un article dans Le Parisien ou d'un rapport de projet de fin d'études. Vous avez déjà entendu parler d'un professeur qui distribue des modèles à ses étudiants pour rédiger leur rapport de projet de fin d'étude? Avez-vous déjà lu deux bon romans qui pourraient correspondre à un même modèle ? Abandonnez cette idée.

Personal tools