Concevoir des documents dans le cadre d'Agile

Sur mon lieu de travail, nous sommes confrontés à un défi dans la mesure où «agile» signifie trop souvent «exigences vagues, mauvais critères d'acceptation, bonne chance! Nous essayons de régler ce problème dans le cadre d'un effort d'amélioration général.

Donc, dans le cadre de cela, je propose que nous générions des documents de conception qui, au-delà du niveau de la user story, reflètent fidèlement le résultat des enquêtes préliminaires sur l'effet d'une fonctionnalité donnée dans le système et incluent des réponses aux questions que nous avons demanda l'entreprise.

Existe-t-il une norme efficace pour cela?

Nous sommes actuellement confrontés à une situation où une nouvelle fonctionnalité peut affecter plusieurs domaines de notre système de "grosse boule de boue" , et les estimations commencent à grimper en raison de cette dette technique. J'espère que des processus de conception plus réfléchis peuvent aider.

"exigences vagues, mauvais critères d'acceptation, bonne chance!"

oui, c'est le même genre d'exigences que vous obtenez même si vous essayez de les clouer aussi! (à titre d'exemple, un document de 10 000 exigences qui a pris 4 ans à un client gouvernemental pour créer était encore plein d'incohérences, d'imprécision et même de déclarations internes contradictoires. Si 4 années de documentation sur les exigences ne peuvent pas vous fournir une exigence décente, exacte, faites vous pensez que vous pourrez obtenir quelque chose de non vague?)

Donc ... la manière agile a été inventée pour comprendre que cela se produit et pour travailler avec elle plutôt que d'essayer de travailler contre elle.

Vous commencez par demander «que voulez-vous» et le client répond «quelque chose comme ça». Vous travaillez, puis vous retournez chez le client et vous dites "est-ce que c'est ce que vous vouliez?", Et le client dit généralement "oui mais ...", après quoi vous demandez "qu'est-ce que vous voulez".

Finalement, vous obtenez exactement ce que le client voulait, même s'il ne sait pas ce que c'est! (bon sang, ils ne savent jamais ce qu'ils veulent, pas exactement).

Dans notre équipe, depuis que nous sommes devenus agiles, nous avons également essayé de réduire et de comprendre la quantité de documentation réellement requise. Je peux partager avec vous ce que nous avons appris jusqu'à présent.

Avant toute chose, assurez-vous de lire cet article sur la documentation Agile / Lean . Très bonne lecture.

Deuxièmement, je vous conseillerais fortement de reconsidérer la production de documents de conception après un travail préliminaire sur les histoires. Nous avons déjà essayé cela et cela s'est avéré être un gaspillage. Au milieu de la dernière version, nous avons décidé de mettre à jour les documents de conception UNIQUEMENT APRÈS la livraison du code de l'histoire. Et maintenant je pense même que c'est trop tôt.

Vous devez vous demander pourquoi vous souhaitez créer des documents de conception avant de coder. Pour nous, ce sont les raisons:

1. En tant qu'équipe, nous devons comprendre comment l'histoire affectera la conception.
2. La possession de documents de conception s'est avérée utile lorsque de nouveaux membres (ou temporaires) se joignent à l'équipe ou lors du retour au code sur lequel personne n'a travaillé depuis plus d'un an. Ils sont donc utiles pour la mémoire organisationnelle pour aider à comprendre le fonctionnement du code.
3. Les documents de conception sont utiles pour les ingénieurs de maintenance qui peuvent avoir besoin de dépanner le code après la publication.

Pour satisfaire (1), vous n'avez pas besoin de produire un document de conception réel. Votre équipe doit toujours avoir une phase de conception avant le codage, mais cette phase peut être aussi simple qu'une session de 15 minutes devant un tableau blanc ou une serviette. Vous n'avez pas besoin de produire un document réel qui prendra des heures (sinon des jours) à écrire juste pour discuter des changements de conception.

(2) ou (3) ne sont pas nécessaires pendant le développement de l'histoire actuelle et plus que probablement ils ne seront pas nécessaires pour plusieurs itérations ultérieures.

Gardez également à l'esprit que chaque fois qu'un membre de l'équipe écrit / met à jour des documents de conception, c'est le moment où le code n'est pas écrit. Lorsque vous écrivez des documents avant le code réel, il y a presque 100% de chances qu'ils nécessitent une mise à jour car une fois que vous commencez à coder, la conception finit toujours par être modifiée. Et même si vous écrivez des documents de conception après le code, comme notre équipe l'a appris, la refactorisation des histoires suivantes modifie toujours la conception.

Donc ce que je recommanderais:

1. Produisez initialement suffisamment de conceptions / modèles temporaires pour que votre équipe puisse avoir une conversation intelligente avant de coder. Ne vous attendez pas à les conserver et ne perdez pas de temps à les formaliser.
2. Produisez uniquement la documentation de conception officielle si quelqu'un en a besoin (c.-à-d. Que votre équipe a un réel besoin de mémoire organisationnelle)
3. Produisez uniquement la documentation de conception sur le code qui a été stabilisé. Il est inutile d'essayer de documenter un module qui ne cesse d'être modifié à chaque itération.
4. Produisez des documents de conception qui décrivent entièrement un module (ou une partie du produit). Dans le passé, nous écrivions des documents de conception qui documentaient les modifications à apporter. Ces documents étaient complètement sans valeur dès la sortie de la version.
5. Gardez le document de très haut niveau. Si vous écrivez 20 pages couvrant l'architecture et la conception de très haut niveau, ce document a) sera lu par d'autres personnes et b) aidera les gens à se familiariser avec la mise en page générale de votre code. Pour plus de détails, les gens peuvent aller directement dans le code. Si vous écrivez 700 pages de spécifications détaillées, elles ne correspondront presque toujours pas à la réalité, c'est trop pour quiconque de lire et vous finirez par devoir maintenir et mettre à jour 700 pages au lieu de 20 chaque fois que de futures modifications seront apportées.

Le "mantra" Agile ne doit pas se passer entièrement de documentation.

Le mantra Agile est de préférer "un logiciel de travail à une documentation complète ". Mais notez le morceau au bas du manifeste.

Autrement dit, bien qu'il y ait de la valeur dans les articles à droite , nous valorisons davantage les articles à gauche. "

Oncle Bob a une bonne politique de documentation

Ne produire aucun document à moins que son besoin ne soit immédiat et significatif .

Vous avez raison de dire que certaines personnes utilisent Agile comme excuse pour ne pas produire de documentation, mais c'est mauvais Agile. C'est ignorer les bits que j'ai mis en évidence dans les citations ci-dessus.

Cela dit, lorsque vous dites "nous sommes actuellement confrontés à une situation où une nouvelle fonctionnalité peut affecter plusieurs domaines de notre système" grosse boule de boue "", si vous allez être agile, vous devez faire quelque chose à ce sujet.

Lorsque vous avez votre documentation, utilisez-la pour modulariser votre code. De cette façon, vous supprimez le besoin à long terme de maintenir la documentation (ce qui ne se produira pas) en supprimant le besoin à long terme de la documentation.

c'est à dire. Rendez le besoin immédiat et significatif.

Ce qui est agile, c'est que les efforts de documentation doivent vraiment être dirigés par l'équipe Scrum. Si les développeurs ne pensent pas que la documentation externe est suffisante pour leurs besoins, la user story est bloquée jusqu'à ce qu'ils le fassent. Si l'entreprise estime que les développeurs ne produisent pas de documentation adéquate, le propriétaire du produit insiste pour l'intégrer aux critères d'acceptation. Pour cette raison, j'ai trouvé notre documentation plus ciblée et plus efficace depuis le passage à Scrum.

Nous utilisons VersionOne pour suivre nos histoires d'utilisateurs, mais je suis sûr que nos méthodes s'appliquent à d'autres systèmes. Il vous permet de joindre des fichiers à des user stories. Nous avons trouvé que c'était un endroit extrêmement utile pour mettre des documents de conception.

Pour un exemple qui a très bien fonctionné pour nous, nous avions besoin de tester une nouvelle conception de carte de circuit imprimé aussi rapidement que possible après la construction du prototype. Nous avons créé deux user stories pour tout ce qui nécessitait des tests: une pour concevoir le test et une pour exécuter le test. Un critère d'acceptation pour le scénario de conception était que la procédure de test était entièrement documentée dans le scénario d'exécution.

Lorsque nous sommes arrivés à la partie test, cela s'est passé plus facilement que je ne l'ai jamais vu. Nous venons d'ouvrir la user story et avons suivi la procédure étape par étape. La documentation était exactement ce dont nous avions besoin pour terminer l'histoire, ni plus ni moins.

Nous avons une autre histoire dans notre carnet de commandes juste pour améliorer la documentation d'une puce que nous utilisons, afin de permettre aux autres équipes de la récupérer plus facilement pour leurs propres produits.

En résumé, si vous sentez que votre documentation souffre, la solution est aussi simple que d'en faire une user story séparée et / ou de l'intégrer dans les critères d'acceptation.

Lorsque vous parlez d'exigences médiocres, la première chose qui me vient à l'esprit est de vous assurer que vous disposez des critères de test. Si possible, créez des cas de test automatisés réutilisables pour les parties existantes du système. Une fois que tout le monde est à l'aise avec cela, passez à l'écriture des cas de test avant l'écriture du code. De bons scénarios de test peuvent faire beaucoup pour documenter les comportements d'un système.

Quant aux documents de conception spécifiques à utiliser, comme d'autres l'ont déjà dit, cela dépend fortement des besoins de l'équipe et de la prochaine tâche qu'elle entreprendra. Lorsque cela est possible, essayez d'utiliser des outils qui peuvent générer les documents (à partir du code) que vous utiliseriez ou générer le code à partir du document. La maintenance de la documentation peut devenir assez coûteuse, alors choisissez judicieusement lorsque vous persistez un document de conception.

Personnellement, j'ai eu un bon succès avec les diagrammes de classes générés à partir du code et des cas de test fitnesse. L'équipe imprime quelques diagrammes de classe, fait une séance de balisage avec le propriétaire du produit, puis formule une estimation à partir de là. En ce qui concerne fitnesse, j'ai la chance de travailler avec quelques propriétaires de produits qui sont très bons pour exprimer ce qu'ils veulent dans des feuilles de calcul, qui sont ensuite converties en tableaux pour fitnesse.