Come documentare un progetto che è già stato sviluppato?

Vorrei sapere quali opzioni sono disponibili per documentare un progetto che è già stato sviluppato, poiché gli sviluppatori che hanno lavorato non hanno scritto nemmeno una singola pagina di documentazione.

Il progetto non ha altri dettagli oltre a molte pagine di script con funzioni scritte e modificate dagli sviluppatori che hanno lavorato a questo progetto negli ultimi 2 anni. Tutto quello che ho è lo schema del database e i file di progetto. Vorrei sapere se esiste un modo per organizzare questo progetto e documentarlo in modo che possa essere utile per gli sviluppatori che lavoreranno su questo progetto in futuro.

Il progetto è stato sviluppato con PHP e MySQL. Le funzioni sono scarsamente commentate, quindi non riesco a ottenere buoni risultati quando lo eseguo con doxygen.

Chi leggerà la documentazione? A cosa servirà 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 necessaria e non di più. Molte organizzazioni richiedono documentazione perché qualcuno ha insistito sul fatto che è la migliore pratica, ma la documentazione finisce per raccogliere polvere.

Supponendo che le persone utilizzino effettivamente la documentazione, non tentare di acquisire il codice e il database al livello più piccolo. Gli sviluppatori esamineranno il codice per le minuzie. Invece, concentrarsi su dettagli che non sono evidenti nel codice , ad esempio:

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

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

Buoni test di unità automatizzati o casi di test possono anche essere una documentazione utile, sebbene difficile da accedere per persone meno tecniche.

Sembra anche che sia necessario apportare un cambiamento culturale per includere la documentazione . Iniziare in piccolo ma, idealmente, il progetto non dovrebbe essere "fatto" fino a quando non abbia almeno un livello minimo di documentazione. Questo è probabilmente il passo più difficile perché quanto sopra sono cose che puoi controllare. Questo è qualcosa in cui gli altri devono acquistare. 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 come questa sedendomi con i vari proprietari di prodotti o utenti esperti, esaminando i loro casi d'uso principali e documentandoli con una serie di test. Puoi usarli come base per il sistema quando inizi a apportare modifiche in futuro. Questo può anche aiutare a identificare le aree del sistema che non hanno un proprietario o un caso d'uso e che possono essere potenzialmente eliminate.

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

In generale, suggerisco di evitare la documentazione vecchio stile 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 si evolve.

Per prima cosa, qual è il tuo pubblico target? Futuri sviluppatori o altre persone d'affari? Con in mente la risposta a questa domanda:

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 nello schema più ampio delle cose. Spiega su cosa funziona, come si inserisce nella rete e parla con qualsiasi altro sistema. Quindi analizzerei ciascuna schermata, lo catturerei e darei una rapida spiegazione di ciò che fa lo schermo e di come interagisce con qualsiasi altra parte del sistema. Se è per gli sviluppatori, mantienilo come se stessi spiegando loro l'app per la prima volta. Dopo tutto, questo è il punto del documento (presumo).

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

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

I suggerimenti precedenti sono tutti buoni, ma prenderei anche in considerazione la ricerca se la tua comunità di utenti ha creato personalmente una documentazione ad hoc. La tua domanda non specifica se una versione del tuo "prodotto" (esistente da due anni) è mai stata rilasciata agli utenti. Se è stato utilizzato e non c'è documentazione ufficiale, allora non è stata necessaria alcuna documentazione, oppure esiste una documentazione "non ufficiale" che può essere rudimentale, ma probabilmente percepita come essenziale dagli utenti. Prova a cercare nel Web artefatti che potrebbero rappresentare API critiche, cercare forum, chiedere agli utenti esperti e cercare siti di domande e risposte. Se possibile, prova a scrivere la documentazione che soddisfi un'esigenza tecnica o aziendale.

La domanda è: vuoi documentarla così com'è adesso o come dovrebbe essere?

Quello che ho letto dalla tua domanda è che stai pensando alla documentazione dell'API e non a tanta documentazione per l'utente e il codice forse non è così ben mantenuto e criptico.

Temo che se documenti ora, finirai per buttare via gran parte del tuo lavoro, una volta che il codice sarà riformulato.

Vorrei adottare il seguente approccio:

• rendere la documentazione non necessaria il più possibile aderendo alle migliori pratiche comuni. Scegli nomi di buone classi, nomi di metodi, nomi di variabili che puoi capire intuitivamente
• abbattere enormi classi di mostri e / o funzioni dove ha senso
• utilizzare i commenti PHPdoc: è possibile utilizzare gli strumenti per creare la documentazione API
• scrivere test per questo: i test ti aiuteranno a capire o definire cosa dovrebbe fare il codice.

Ora, hai ancora cose prive di documenti: questi potrebbero essere i concetti generali, l'architettura ecc. Per questo, scriverei effettivamente la documentazione, ma scrivo solo ciò che è veramente utile e utile.