Come documentare un progetto già sviluppato?

Chi leggerà la documentazione? Per cosa verrà utilizzata la documentazione? Queste sono le domande più importanti a cui rispondere. Ad esempio, la documentazione per gli sviluppatori di manutenzione si concentrerebbe maggiormente sulla struttura, mentre la documentazione per gli sviluppatori che si integrano con il prodotto si concentrerebbe maggiormente sui servizi Web e sulla struttura del database.

In generale, fai tutta la documentazione richiesta e non di più. Molte organizzazioni richiedono documentazione perché qualcuno ha insistito sul fatto che è una buona pratica, ma la documentazione finisce per accumulare polvere.

Supponendo che le persone effettivamente utilizzeranno la documentazione, non provare ad acquisire il codice e il database al livello più piccolo. Gli sviluppatori guarderanno il codice per le minuzie. Invece, concentrati sui dettagli che non sono evidenti nel codice , ad esempio:

1. I casi d'uso che il prodotto soddisfa. Questo può essere difficile considerando l'età del prodotto, ma catturare ciò che il prodotto è destinato a fare dà un contesto vitale ai lettori e ai tester non tecnici. Chi sono i concorrenti sul mercato (se ce ne sono)? Esiste qualcosa escluso dall'ambito del prodotto?
2. Qualsiasi chiaro requisiti non funzionali . Ad esempio, il prodotto è stato scritto per gestire un determinato volume? Quanti anni possono avere i dati? Dove viene utilizzato il caching? Come vengono autenticati gli utenti? Come funziona il controllo degli accessi?
3. Un diagramma di contesto che mostra l'interazione con altri sistemi, come database, origini di autenticazione, backup, monitoraggio e così via.
4. (Se noto) Rischi e come sono stati mitigati insieme a un registro delle decisioni . Questo è probabilmente difficile in retrospettiva, ma ci sono spesso decisioni critiche che influenzano un design. Cattura quelli che conosci.
5. Comuni design patterns o linee guida per la progettazione . Ad esempio, esiste un modo standard per accedere al database? C'è uno standard di codifica o di denominazione?
6. Percorsi di codice critico , in genere utilizzando diagrammi di flusso o attività UML o diagrammi di sequenza. Nel progetto potrebbero non esserci, ma questi sono di solito quelli che gli utenti aziendali hanno articolato.

Anche se tutte queste informazioni non sono disponibili, inizia ora . Gli sviluppatori che verranno dopo ti ringrazieranno

I buoni unit test o test automatizzati possono anche essere una documentazione utile, anche se difficile da accedere per le persone meno tecniche.

Sembra anche che tu debba apportare una modifica culturale per includere la documentazione . Inizia in piccolo ma, idealmente, il progetto non dovrebbe essere "completato" finché non avrà almeno un livello minimo di documentazione. Questo è probabilmente il passo più difficile perché sopra sono le cose che puoi controllare. Questo è qualcosa in cui gli altri devono comprare. Tuttavia, può anche essere il più gratificante, in particolare se il prossimo progetto che fai viene fornito con una buona documentazione.

In passato ho gestito una situazione del genere sedendomi con i vari proprietari di prodotti o utenti esperti, esaminando i loro casi d'uso primari e documentandoli con una serie di test. Puoi utilizzarli come una linea di base per il sistema quando inizi a fare cambiamenti in futuro. Ciò può anche aiutare a identificare le aree del sistema che non hanno un proprietario o un caso d'uso e potrebbero essere potenzialmente eliminate.

Tutto dipende davvero dalla dimensione del sistema. Se si tratta di un sistema complesso con molti stakeholder diversi, è possibile creare un diagramma di componenti di alto livello che descriva dettagliatamente quali funzionalità esistono e dove sono soddisfatte. Questo può essere molto utile per identificare i problemi architettonici nella progettazione del sistema.

In generale, suggerisco di evitare la documentazione obsoleta perché diventerà obsoleta e in futuro mancherà agli sviluppatori. Cerco sempre di produrre documentazione vivente sotto forma di test che verranno mantenuti man mano che il sistema evolve.

Per prima cosa, chi è il tuo pubblico di destinazione? Sviluppatori futuri o altre persone d'affari? Con la risposta a questa domanda in mente:

Come altri hanno già detto, una descrizione di alto livello è la prima cosa di cui hai bisogno. Spiega cosa sta cercando di fare il sistema nel più ampio schema di cose. Spiega cosa funziona, come si inserisce nella rete e parla con qualsiasi altro sistema. Quindi vorrei esaminare ogni schermata, visualizzarla e dare una rapida spiegazione di ciò che lo schermo fa e di come interagisce con qualsiasi altra parte del sistema. Se è per gli sviluppatori, mantienilo in conversazione come se stessi spiegando l'app a loro per la prima volta. Dopo tutto, questo è il punto del documento (suppongo).

Qualsiasi elaborazione o logica complicata utilizzerei un diagramma di stato, un diagramma di flusso di dati o un diagramma di sequenza. Definitivamente fare un diagramma di entità, quindi un disegno di schema di DB (due cose diverse!). Forse un semplice diagramma di classe, ma mantienilo semplice, nota solo le cose principali che sono di tuo interesse, gli sviluppatori possono capire quella roba guardando il codice.

Se hai problemi a iniziare, fai finta che ci sia un altro sviluppatore nella stanza accanto a te, che non conosce la prima cosa sul sistema, sono relativamente impaziente e ha solo bisogno di conoscerne l'essenza . Quindi inizia a spiegare e scrivi ciò che dici:)

I suggerimenti precedenti sono tutti validi, ma vorrei anche esaminare se la tua comunità di utenti abbia creato personalmente una documentazione ad hoc. La tua domanda non specificava se una versione del tuo 'prodotto' (esistente per due anni) è mai stata rilasciata agli utenti. Se è stato utilizzato, e non c'è documentazione ufficiale, non è stata necessaria alcuna documentazione o esiste una documentazione "non ufficiale" che può essere rudimentale, ma probabilmente anche percepita come essenziale dagli utenti. Prova a cercare nel web gli elementi che possono rappresentare le API critiche, i forum di ricerca, chiedi ai power user e cerca nei siti di domande e risposte. Se possibile, prova a scrivere documentazione che soddisfi le esigenze tecniche o aziendali.