A quale fase di un progetto si dovrebbe fare la documentazione?

Question

A quale fase di un progetto si dovrebbe fare la documentazione?

#1 da (10 voti)
#2 da (4 voti)

6

Mi è stato assegnato per risolvere alcuni problemi in un progetto PHP. Più tardi, mi è stato chiesto di implementare alcune nuove funzionalità, cosa che ho fatto. Il progetto non utilizza alcun framework né utilizza OOP. Manca una struttura adeguata, fatta eccezione per l'uso di cartelle (senza sottocartelle) per organizzare i file. Non c'era documentazione creata dal programmatore originale. Ora, il progetto è quasi completo con alcuni semplici test da eseguire e il cliente chiede documentazione.

In realtà ho alcune domande.

Ho sempre considerato la documentazione come un processo che inizia prima di iniziare la parte di codifica del progetto e che continua fino alla fine. Quindi, mi sbaglio di questo? La documentazione è alla fine del progetto?
Quale dovrebbe essere il mio modo di documentare questo progetto. Ho conservato una documentazione di base come "log like" sui cambiamenti che ho apportato per uso personale. Ma poiché non è stata prodotta alcuna documentazione iniziale, non mi sono nemmeno preoccupato di crearne una.
C'è un buon modello di documentazione che potrei usare per ridurre il mio impegno?

_{Sto parlando o documentazione del codice (non la documentazione dell'utente). Anche se sto assumendo questo dato che non hanno specificato nulla.}

development-process documentation

posta rahules 14.02.2013 - 16:07

fonte

2 risposte

4

Hai ragione, la documentazione dovrebbe iniziare prima di iniziare la codifica. Tuttavia, è un processo continuo poiché la documentazione dovrebbe cambiare con il progetto.
Documentare le tue modifiche da solo potrebbe non essere sufficiente. È bene iniziare con le modifiche che hai apportato, ma ancora meglio se ti prendi il tempo necessario per documentare l'intero codice base. So che questo può essere un dolore, ma le cose buone difficilmente vengono facili.
I wiki sono un buon modello di documentazione. Prova DokuWiki link . Lo sviluppo in linguaggi come Java semplifica la documentazione in quanto vi sono strumenti che generano documentazione dai commenti nel codice. Ma non sono sicuro che tu abbia lo stesso lusso con PHP.

risposta data 14.02.2013 - 16:19

fonte

Leggi altre domande sui tag development-process documentation

Processo di revisione del codice quando si utilizza GIT come repository? Algoritmo per confrontare centinaia di documenti simili, ma non identici

score 10 · Accepted Answer

Benvenuti nel lato noioso e noioso dell'ingegneria del software, prodotti di reverse engineering già in vostro possesso!

Questo è in gran parte un lavoro per far sembrare che tu sappia quello che stai facendo e la società non sia abbastanza incompetente da saltare una fase cruciale del processo, anche se lo sono. In teoria, qualsiasi tipo di documentazione aiuterà gli altri programmatori a fare un passo avanti nel progetto, quindi se trovi qualcosa che ti confonde, scrivi una spiegazione a riguardo dopo averlo capito.

1) Hai assolutamente ragione. La maggior parte della documentazione (dovrebbe) venire prima che il prodotto è fatto. Cose come requisiti, design, test. Altri, tuttavia, dovrebbero essere realizzati in seguito; manuali degli utenti, tracciabilità, controlli di qualità.

2) Se il cliente lo richiede, è necessario effettuare l'immersione e produrre la documentazione desiderata.

3) Ci sono molti modelli diversi là fuori. Google in giro per SRS, specifiche dei requisiti software, SDD, descrizione del design del software o persino modelli DO-178, se vuoi essere sepolto in documenti fino alla fine dei tuoi giorni.

Ma di gran lunga, fai abbastanza documenti per rendere felice il cliente, come hai già perso la barca per la sua utilità. A meno che, naturalmente, questo progetto abbia una lunga vita davanti a sé. In tal caso, dovresti davvero metterlo in pratica prima che diventi qualcosa di ingestibile.