Come dovrei scegliere la documentazione giusta per il mio team?

In Sviluppo software agile , lo zio Bob ha scritto una volta la sua prima legge di documentazione "Non produrre documenti se non è necessario è immediato e significativo. " Come è stato tipico di tali commenti nel mondo Agile, questo è stato erroneamente erroneamente interpretato erroneamente. Quindi in seguito ha chiarito .

Agile Methods require two kinds of documentation: Requirements and Design Documents. All other kinds of documents are optional within Agile Methods; but optional does not mean absent.

Requirements. In Agile Methods, the requirements are documented one iteration at a time. Requirements are often identified long in advance of their development, but they are not fleshed out until the iteration in which they are developed begins. Moreover, they are written as automated acceptance tests. Other kinds of requirements documentation, such a narratives, workflows, and storyboards may also optionally be created.

Design Documents. In Agile Methods the design is documented by creating unit tests using Test Driven Development. These unit tests are working examples of how to use each part of the code. Other kinds of design documents, such as class diagrams, interaction diagrams, state charts, ER diagrams, etc. may optionally be created too.

Nota l'ultimo paragrafo in particolare. A volte è ridicolo per gli sviluppatori scrivere documentazione per altri sviluppatori in inglese . Non dimenticare mai che esiste un altro linguaggio comune che gli sviluppatori parlano: codice. A differenza dell'inglese, il codice è auto-validante.

L'utilizzo di unit test per documentare l'intento del codice dell'applicazione è un modo brillante di scrivere documentazione. Perché? Perché sono garantiti per rimanere aggiornati.

Inoltre, e forse più rilevante per la tua situazione, scrive:

Documents that the development team decides they need, are simply created as and when they are needed. Documents that the business decides they need, and that the development team does not need for their own purposes, are written as story cards, and estimated, planned and scheduled as all story cards are. If they never get selected for an iteration, then they must not have been all that valuable to the business. If, however, they get scheduled for an iteration, the business must have considered them important enough to schedule.

Questa è una tecnica che uso sempre per capire che cos'è una documentazione veramente utile. Se il team di sviluppo ritiene di averne bisogno, basta dare loro i mezzi (un wiki) e lo scriveranno, senza essere chiesti. Se l'azienda ritiene di averne bisogno, accodala come un lavoro accanto a tutto il resto e controlla se decide che ne ha bisogno più del necessario.

Dovresti concentrarti su ciò che il tuo team leggerà effettivamente. Non ha alcun senso concentrarsi su nulla, se non hai la minima idea di come la tua squadra risponderà.

La soluzione migliore è rendere la documentazione parte del processo e includere tutti gli utenti. Ci dovrebbe essere una certa coerenza, ma preoccupiamoci di questo quando c'è una documentazione vera e propria. Quello che abbiamo fatto è piuttosto semplice: abbiamo aggiunto una documentazione e una sotto-attività di revisione del codice per ogni problema. Nessun problema è stato risolto, finché tutte le attività secondarie non sono state risolte, quindi tutti devono scrivere la propria documentazione e rivedere il codice degli altri.

Usiamo un wiki, quindi la documentazione è in continua evoluzione e in un primo momento tutti se ne sono occupati a modo loro. Ad esempio, ero l'unico che usava i DFD. Dopo alcuni mesi, abbiamo iniziato a copiare a vicenda lo stile, imparando gli uni dagli altri, e abbiamo raggiunto un punto di documentazione quasi coerente. Sono tornato indietro e ho revisionato i post più vecchi, e diciamo che siamo a un punto in cui la nostra documentazione è abbastanza buona.

Sarebbe meglio non lasciare che qualcuno diventasse troppo creativo, ma a parte questo, avere una documentazione quasi coerente è meglio che preoccuparsi delle best practice e degli standard del settore, e non riuscire mai a scrivere quella dannata cosa.

Per riassumere, le mie linee guida generali per la documentazione sono:

1. Scrivi quella dannata cosa,
2. Sii coerente.
3. Preoccupati per tutto il resto.

Misura e usa le tue misure per guidare l'utente. Probabilmente non puoi (e non dovresti) fare split test sui membri di un piccolo gruppo di programmatori, ma puoi cambiare la documentazione utilizzata in momenti diversi o su componenti diversi.

Introduci DFD: aiutano? ... oh, aspetta, cosa significa "aiutare"? Ci sono un certo numero di quantità che puoi misurare: velocità della squadra, densità dei difetti, soddisfazione della squadra e probabilmente altre. Quindi scegli le misurazioni che sono importanti per le prestazioni del tuo team e scopri in che modo i diversi processi / artefatti della documentazione li riguardano.

Il punto qui è che la documentazione è uno strumento di comunicazione, quindi rispondere "quale documentazione dovremmo usare?" si rivolge tacitamente "come comunica il mio team?" Non lo so, ma puoi scoprirlo e puoi adattare la tua strategia di documentazione per aiutare le persone della tua squadra.

What would be the best types of documentation for my team?

Non sono sicuro che la documentazione di sistema abbia i tipi standard. Tuttavia, la documentazione del sistema ha degli obiettivi. Questi obiettivi derivano dalla metodologia utilizzata e dalla fase di sviluppo del sistema utilizzata. La documentazione del sistema è influenzata anche da standard come CMM.

Should we focus on DFDs, sequence diagrams, class diagrams, just plain text... ?

Ogni tipo di diagramma ha uno scopo ed è solitamente legato a una metodologia. I DFD fanno parte di Structured Analysis e sono comunemente usati per descrivere i flussi di dati attraverso sistemi, programmi e per descrivere input e output di sistema (o sottosistema). I diagrammi delle classi fanno parte del mondo UML e OOA / OOD. I diagrammi delle classi vengono utilizzati per documentare le classi in un sistema / sottosistema e in molti casi come base per altri diagrammi e per generare DDL. Il testo semplice è importante per specificare e descrivere le regole aziendali.

Are some documentation methodologies better for specific industries or are there some which are just a waste of time?

Contrariamente a quanto si crede, la documentazione NON è una perdita di tempo se eseguita in modo coerente e corretto.

Quello che devi fare è studiare il valore della documentazione e mettere in atto i documenti specifici che descriveranno il tuo sistema e che aggiungeranno valore in ciascuna delle fasi di sviluppo del sistema, quindi istruisci il tuo team nelle tecniche e nel valore di questo lavoro. La cosa più importante è pianificare tutto questo nel programma del progetto.

Non fornire documentazione stampata al tuo team perché i requisiti di progetto e l'architettura di implementazione cambiano durante la vita del progetto: Gli sviluppatori non leggono anche la documentazione stampata Non appena l'implementazione del codice oi requisiti vengono modificati, la documentazione non è più accurata.

Detto questo, non ho proiettili d'argento se non per creare diagrammi di classe sincronizzati con requisiti e codice.