Qu'est-ce qui fait une bonne spécification ?

Question

L'un des éléments de la Joel Test est qu'un projet/une entreprise doit avoir un cahier des charges.

Je me demande ce qui fait qu'une spécification est bonne. Certaines entreprises rédigent des volumes de spécifications inutiles que personne ne lit jamais, d'autres n'écrivent rien parce que "personne ne les lira de toute façon". Alors, que mettez-vous dans vos spécifications ? Quel est le bon équilibre entre les deux extrêmes ? Y a-t-il quelque chose de particulièrement important qui doit vraiment, vraiment ( !) toujours être consigné dans une spécification ?

Answer 1

La meilleure spécification est celle qui :

1. Existe
2. Décrit le QUOI, pas le COMMENT (pas de solutions)
3. Peut être interprété de la manière la plus simple possible.
4. est largement distribué
5. est reconnu comme étant LA spécification par toutes les parties concernées.
6. Est concis
7. Est cohérent
8. est mis à jour régulièrement en fonction de l'évolution des besoins
9. Décrire le problème dans toute la mesure du possible et du possible.
10. Est testable

Answer 2

Que mettre dans un cahier des charges

Vous devez examiner le public auquel s'adresse la spécification et déterminer ce qu'il doit savoir. S'agit-il simplement d'un document entre vous et un sponsor commercial ? Dans ce cas, il peut probablement être assez léger. S'il s'agit d'une spécification fonctionnelle pour un projet J2EE de plus de 100 années-hommes, elle devra probablement être un peu plus détaillée.

Le public

La question clé est : qui va lire la spécification ? Une spécification aura plusieurs groupes potentiels de parties prenantes :

• Le propriétaire de l'entreprise qui signe le système.

• Le développeur qui construit le système (qui peut être vous ou non)

• Les responsables de l'assurance qualité qui doivent rédiger des plans d'essai.

• Personnel d'entretien souhaitant comprendre le système

• Développeurs ou analystes sur d'autres projets qui peuvent vouloir y intégrer d'autres systèmes.

Exigences des principales parties prenantes typiques :

• Le site propriétaire d'entreprise doit avoir une idée claire des flux de travail et des règles de gestion du système afin d'avoir une chance de comprendre ce qu'il a accepté. S'ils sont le seul public important de la spécification, concentrez-vous sur l'interface utilisateur, le flux de travail à l'écran et les règles de validation des données et des activités.

• Développeurs ont besoin d'un modèle de données, de règles de validation des données, d'une partie ou de la totalité de la conception de l'interface utilisateur et d'une description suffisante du comportement attendu du système pour savoir ce qu'ils doivent construire. Si vous écrivez pour des développeurs, concentrez-vous sur l'interface utilisateur, la mise en correspondance avec le modèle de données et les règles de l'interface utilisateur. Ces éléments doivent être plus détaillés que si vous effectuez le développement vous-même, car vous agissez en tant qu'intermédiaire dans une communication entre deux tiers.

  Si vous spécifiez une interface entre deux systèmes, cela doit être très précis.

• Personnel AQ ont besoin de suffisamment d'informations pour savoir comment tester et valider la logique, la validation et le comportement attendu de l'interface utilisateur de l'application. Une spécification destinée aux développeurs et au personnel d'assurance qualité doit être assez claire.

• Personnel d'entretien ont besoin des mêmes informations que les développeurs, ainsi que d'une feuille de route décrivant l'architecture du système.

• Intégrateurs ont besoin d'un modèle de données et de définitions claires de toutes les interfaces.

Les éléments clés d'un cahier des charges :

Je suppose qu'il s'agit de rédiger des spécifications pour des applications professionnelles, et le contenu ci-dessous est donc orienté dans ce sens. Les spécifications pour d'autres types de systèmes auront une importance différente. D'après mon expérience, les éléments clés d'une spécification fonctionnelle sont les suivants :

• Interface utilisateur : des maquettes d'écran et une description du comportement d'interaction du système et du flux de travail entre les écrans.

• Modèle de données : Définition des éléments de données et mise en correspondance avec l'interface utilisateur. Les mappages de l'interface utilisateur sont normalement effectués dans les bits de la spécification décrivant l'interface utilisateur.

• Validation des données et règles de gestion : Quels contrôles d'exactitude doivent être effectués sur les données et quels calculs sont effectués, ainsi que les définitions. Les exemples peuvent être très utiles à cet égard.

• Définitions des interfaces : Si vous avez des interfaces exposées que d'autres systèmes peuvent utiliser, vous devez les spécifier de manière assez stricte. Les RFC Internet les plus simples donnent d'assez bons exemples de conception de protocoles et constituent un bon point de départ pour des exemples de documents d'interface. Il n'est pas facile de définir clairement les interfaces, mais cela vous évitera certainement des ennuis par la suite.

• De la colle : C'est là que les cas d'utilisation, les diagrammes de flux de travail et autres artefacts liés aux exigences sont utiles. En général, il est inutile d'en dresser une liste exhaustive, mais il y aura des zones clés dans le système où ce type de documentation aidera à mettre les éléments en contexte. D'après mon expérience, l'inclusion sélective de cas d'utilisation et d'autres descriptions au niveau des exigences contribue grandement à la clarté et à la signification d'une spécification, mais rédiger une histoire d'utilisateur pour chaque interaction avec le système est une perte de temps.

Joel (célèbre pour ses "logiciels") a rédigé une bonne série d'articles sur ce qui est appelé Spécification fonctionnelle indolore auquel j'ai renvoyé des gens à de nombreuses occasions. C'est un bon ensemble d'articles qui vaut la peine d'être lu. À mon avis, votre objectif est d'expliquer clairement ce que le système est censé faire d'une manière qui minimise l'ambiguïté. Il est très utile de considérer la spécification comme un document de référence - ce que les différentes parties prenantes voudraient pouvoir consulter facilement.

Après avoir rédigé une série de points sur les spécifications, la communication claire est plus difficile qu'il n'y paraît. Les spécifications sont en fait des documents techniques non triviaux qui mettent à l'épreuve les compétences rédactionnelles et éditoriales d'une personne. Il s'agit en fait de rédiger un document qui décrit ce que quelqu'un est censé construire. Rédiger de bonnes spécifications est un peu un art.

L'avantage de faire des spécifications est que personne d'autre ne veut les faire. Comme vous avez écrit ce qui est probablement le seul document de quelque importance pour le système, c'est vous qui décidez. Toute autre personne ayant un objectif précis doit soit faire pression sur vous pour modifier les spécifications, soit imposer d'une manière ou d'une autre des spécifications concurrentes au projet. C'est un bon exemple de la puissance de la plume sur l'épée.

EDIT : D'après mon expérience, le débat sur la distinction entre "comment" et "quoi" a tendance à être plutôt égoïste. Dans tout projet non trivial, le modèle de données et l'interface utilisateur font intervenir de multiples parties prenantes, qui ne sont pas toutes des développeurs du système. Travailler dans le domaine de l'entreposage de données vous donnera un avant-goût du chaos qui s'installe lorsqu'on laisse le modèle de données d'une application devenir un fourre-tout. PFS devrait donner une idée de l'ensemble potentiel des parties prenantes auxquelles une spécification doit s'adresser.

Le fait que quelqu'un soit propriétaire d'un modèle de données ou de la conception d'une interface utilisateur ne signifie pas que ces décisions sont prises par fiat - il peut y avoir un processus de discours et de négociation. Cependant, plus un projet est important, plus la valeur de la propriété et de la cohérence de ces éléments augmente. J'ai observé par le passé que la meilleure façon d'apprécier la valeur d'un bon analyste est de voir les dégâts causés par un mauvais analyste.

Answer 3

D'après mon expérience, une spécification aura plus de chances d'être lue si elle comporte les éléments suivants :

• Utilisez des diagrammes lorsque cela est possible - les images valent 1000 mots.
• Avoir une page de titre qui indique clairement ce que décrit la spécification.
• Avoir un style qui est utilisé dans tout le document. Faites en sorte que tous les en-têtes aient la même police, la même taille et le même style. Faites en sorte que la police soit la même tout au long du document, utilisez les mêmes styles de puces, etc.
• N'ÉCLAIRCISSEZ PAS - Soyez clair, concis et précis, et n'ajoutez pas d'éléments supplémentaires pour étoffer votre document. Si un point ne peut être expliqué en quelques lignes de texte, vous devez peut-être le décomposer davantage.

J'ai vu des entreprises où la personne qui rédige les spécifications ne comprend pas le système. C'est presque une façon d'apprendre le système en écrivant la spécification. Cela se termine généralement par des larmes...

Answer 4

En tant que personne qui développe des logiciels sur mesure pour des clients, la meilleure spécification est celle que le client a signée. .

Peu importe le degré de raffinement de vos spécifications - si le client ne les a pas explicitement acceptées par écrit, il les modifiera et s'attendra à ce que vous vous adaptiez à leurs changements de manière transparente, détruisant ainsi votre magnifique architecture...

Answer 5

Une bonne spécification doit contenir des exigences mesurables et vérifiables. En examinant chaque exigence, vous devez pouvoir répondre facilement à la question suivante : "Comment puis-je prouver que j'ai rempli cette exigence ?".