Gestion de la rédaction des spécifications

9

Je ne peux tout simplement pas imaginer écrire un logiciel sans spécification. Peu importe à quel point il est sommaire ou de haut niveau, il est important d'expliquer aux programmeurs désemparés quelles sont les fonctionnalités du programme.

Mais le problème avec la spécification est qu'elle est un peu un citoyen de seconde classe dans tout le cycle de développement logiciel; lorsque le développement prend de la vitesse, il est négligé. Mais quand un différend survient, les développeurs et les testeurs et les vendeurs se démènent pour trouver les spécifications pour justifier leurs motifs.

Un ou plusieurs scénarios se produiront:

  1. La spécification ne peut pas être récupérée, personne ne sait où se trouve la spécification
  2. Différentes versions de la spécification émergent de différentes sources; il faut de grandes difficultés à savoir quelle version est la dernière version, ou s'il est une dernière version disponible.
  3. La spécification est incomplète, certaines parties des documents auxquels elle fait référence sont manquantes.

La gestion des spécifications est donc importante, et il est tout aussi important que tout le monde ne dispose que d'une seule source de spécifications.

Comment gérez-vous vos spécifications? J'ai essayé d'amener tout le monde à utiliser Google Docs, mais tout le monde s'y est opposé. Tout le monde est trop attaché et amoureux de Microsoft Word, ce qui est - à leur avis - très facile à utiliser, très facile à insérer l'image, très facile à saisir l'équation et ainsi de suite.

Comment les convaincre que MS Word est tout simplement terrible pour le partage?

specifications Graviton
la source

Réponses:

6

Comment les convaincre que MS Word est tout simplement terrible pour le partage?

Ne perdez pas votre temps.

Première. La spécification doit être en texte brut (vraiment) et sous le contrôle du code source. Utilisez Markdown ou RST ou un autre outil de balisage léger pour produire une page PDF ou HTML. Texte brut.

Seconde. Prenez les différentes sources. Fusionnez-les. Écrivez votre propre document final.

Lorsqu'ils s'y opposent, ils ont deux choix.

  1. Utilisez Google Docs (ou l'outil de contrôle du code source) pour modifier votre version.

  2. Continuez à vous envoyer les modifications que vous modifiez, filtrez et transformez en document final.

Je préfère le n ° 2. Quelqu'un doit «posséder» la spécification. Et un tas de gens (de style wiki) mène à des débats et des guerres de changement et des documents annexes et des conversations hors ligne et autres.

S.Lott
la source
1
+1, et rappelez-vous la règle de la moindre puissance - Quiconque veut une version de fantaisie dans un éditeur WYSIWYG peut simplement copier le balisage rendu.
l0b0
@ l0b0: joli lien.
S.Lott
6

Je ne pense pas que ce soit un problème "d'outil" mais plutôt un problème de "processus" (ou d'absence de processus).

Vous avez probablement déjà un processus pour publier le logiciel (test unitaire, test d'intégration, lettre de sortie, livraison, etc.), vous devez également implémenter un processus de documentation.

  • Qui va rédiger les spécifications? Qui va les mettre à jour ou les maintenir?
  • Qui va revoir les spécifications?
  • Qui va approuver les spécifications? Architecte, chef de projet, QA?
  • Comment les spécifications sont-elles stockées?
  • Qui va s'assurer qu'aucune version obsolète n'est utilisée?
Xavier T.
la source
2
+1: les problèmes d'outils sont souvent des symptômes de problèmes de processus.
S.Lott
nous avons un processus, mais les gens adorent se plaindre que le processus ne fonctionne pas et couper les coins quand cela est possible.
Graviton
@Graviton: votre principal problème est probablement que la direction ne peut pas voir l'utilisation de la documentation et, par conséquent, n'applique pas de règles strictes. Si vous voulez que les choses s'améliorent, vous devrez probablement leur montrer à quel point c'est important.
Xavier T.28
4

Une sorte de contrôle est définitivement nécessaire.

Il doit être versionné et signé, et ce processus doit être strict.

Dans trop d'endroits, la déconnexion est négligée, ce qui conduit à des combats de chignons.

L'emplacement n'a pas d'importance tant qu'il peut être suivi

  • Sharepoint
  • un lecteur partagé sécurisé et sauvegardé
  • J'ai vu certains endroits utiliser leur contrôle de code source !!

Mais plus important encore, vous devez vous rallier à toutes les personnes impliquées et à 1 ou 2 personnes chargées de gérer le document ET la signature, par exemple. le chef de projet.

ozz
la source
+1, je suggère fortement de déplacer le document de spécification vers le contrôle de code source si rien d'autre ne vous aide. Un avantage est que vous obtenez l'historique des versions. Même si vous ne pouvez pas faire de différences de version (sauf si vous trouvez un plugin qui peut faire des différences sur les fichiers Word), vous pouvez toujours extraire toutes les versions et voir ce qui a changé. Cela peut être TRÈS utile dans un litige sur les spécifications. L'approbation est également très bonne. Et aussi l'importance de faire participer tout le monde au processus (afin que personne ne puisse dire "quand cela a-t-il été décidé?") Ne peut pas être suffisamment souligné.
FrustratedWithFormsDesigner
0

MS Word est parfaitement adapté à la création d'une spécification. Nous gérons le nôtre dans SharePoint, qui gère également la gestion des versions. Si vous n'avez pas SharePoint ou un autre produit de gestion de documents à portée de main, Google Docs est OK (vous pouvez maintenant télécharger des fichiers .doc / .docx sans les convertir au format Google Docs). Ou comme d'autres l'ont suggéré, vous pouvez même les stocker dans votre système de contrôle de version de code source (si les personnes créant les spécifications ont accès à ce système).

Marcie
la source
0 
 > How to convince them that MS Word is just terrible for sharing?

vous ne pouvez pas facilement comparer la différence de deux instances dans un système de contrôle de version.

Je n'aime pas les spécifications de mots pour cette raison. Mais comme c'est une décision politique d'utiliser des spécifications de mots, nous avons en première page des "informations historiques" avec ces colonnes:

numéro de version (concerne la version du produit), auteur, date, description

k3b
la source