Documentare una nuova funzione

Per catturare le esigenze dell'utente, puoi prendere in considerazione uno dei seguenti:

• a user story : questo è un modo molto semplice ed efficace per documentare le esigenze degli utenti
• a descrizione del caso d'uso : questo pragmatico approccio di Alistair Cockburn è estremamente semplice da produrre, è appropriato anche per esigenze più complesse ed è facile da capire da chiunque sia coinvolto.
• a use case (2.0) : si basa su un semplice diagrammi UML che si concentrano sugli obiettivi dell'utente e che sono integrati dalla narrativa del caso d'uso. Il "2.0" è stato aggiunto da Ivar Jakobson per aggiungere l'affettamento del caso d'uso, per facilitare un approccio iterativo.
• se si tratta di un sistema aziendale, puoi anche prendere in considerazione un diagramma BPMN . Questi diagrammi sono presenti in un'interazione complessa e di facile comprensione tra diversi attori.

Per documentare la decisione di progettazione, puoi ovviamente utilizzare UML completi diagrammi delle classi , < a href="http://www.uml-diagrams.org/component-diagrams.html"> diagrammi dei componenti , diagrammi di sequenza , diagrammi di attività e stati diagrammi . Ma è difficile mantenere tutti questi diagrammi quando il sistema è progettato.

In alternativa, puoi optare per un approccio molto pragmatico. Non documentare ciò che può essere facilmente recuperato dal codice (ad esempio strutture di classe con proprietà e metodi), ma concentrati su ciò che è più difficile da comprendere:

• panoramica della struttura: un semplice schizzo delle classi principali e della loro relazione
• interazioni: una breve narrazione insieme potrebbe fare
• razionale: il motivo per cui è stato scelto il design, oltre ai rimanenti problemi di progettazione da risolvere.

Per un esempio pratico, consulta il modello di progettazione GoF (non è necessario leggere il libro, ma solo il descrizione di uno dei modelli - ci sono anche siti internet sui modelli di design). Il modello di design decorativo fa esattamente questo: documenta un disegno perticolare, quando è utilizzabile, e che tipo di problemi risolve.

I don't know how to document this kind of stuff

Bene, chiediti cosa vorrebbe sapere un potenziale lettore. Fortunatamente, non devi indovinare, visto che sei questo potenziale lettore: "Voglio che chiunque dovrebbe essere in grado di capire il sistema [...] includendomi in qualsiasi momento in futuro."

A seconda della funzione effettiva che si desidera documentare e della sua complessità, il contenuto del documento può variare. Suppongo che tu lo stia scrivendo solo per sviluppatori, il che limita anche il suo ambito agli aspetti tecnici della funzionalità.

Di solito, la documentazione tecnica include:

• L'architettura generale. Fornisce una panoramica della funzione, nonché il suo contesto nel sistema più grande.

• Le interfacce. Cioè, come uso la funzione, cosa fa e cosa non fa.

• Le dipendenze. In altre parole, ciò che questa funzionalità deve funzionare correttamente e in che modo utilizza tali dipendenze. Questo include non solo il codice al di fuori della funzione, ma anche cose come configurazione, API di terze parti, file, ecc.

• Le decisioni progettuali specifiche che sono state prese e le ragioni di tali decisioni. Questo aiuta a capire perché la funzionalità è stata sviluppata così com'era.

  Questo è particolarmente importante per gli aspetti che sono stati discussi dal team. Ci sono possibilità che i nuovi arrivati (o la stessa squadra sei mesi dopo) inizino a discutere sullo stesso argomento, dimenticando perché è stato deciso in qualche modo.

• Le stranezze. Simile al punto precedente, questo pone l'accento su alcuni aspetti molto specifici della funzione che sono troppo strani per essere compresi semplicemente leggendo il codice.

  Per esempio, può essere una spiegazione del perché, invece di usare un approccio standard e diretto, uno ha scritto trecento righe di codice inventato, e la spiegazione sarebbe che c'è qualche caso limite in cui l'approccio diretto non funzionerebbe .

Ecco come:

1. Read.

2. Fai cose.

3. Documenta brevemente le cose che fai.

4. Chiedi a qualcun altro di lavorare con queste cose.

5. Guarda come la documentazione li aiuta.

6. Incoraggiarli a migliorare la documentazione aggiornandola con ciò che mancava.

7. Elimina le cose inutili.

8. condensa ciò che non puoi eliminare.

9. Torna al passaggio 1.

Credo profondamente che l'ultima persona a fare un compito sia la persona migliore per documentare quel compito. È per questo che amo così tanto la wiki. Chiunque può modificarli. Fare qualcosa di meno di questo presto produrrà una documentazione obsoleta.