Che tipo di rapporto o documentazione aspettarsi dai miei programmatori

Credo che il problema non riguardi la documentazione che dovresti chiedere. Si tratta di come è possibile verificare che sia valido e in realtà aiuterà il nuovo sviluppatore a riprendere la parte precedente. È facile verificare se la funzionalità effettiva funzioni, ma non è facile controllare la documentazione, indipendentemente dal tipo di documentazione che verrà richiesta.

Questo è il modo in cui lo farei: in primo luogo, aggiungerei il requisito di esattamente ciò che desideri. Direi che "Ogni funzionalità dovrebbe essere documentata a sufficienza per consentire ai nuovi sviluppatori di ottenere una comprensione generale di esso, perché esiste e perché è stata implementata così com'era". Lo lascerei agli sviluppatori per decidere il modo migliore per documentare il loro lavoro. Possono creare una documentazione esterna completa o possono rendere il codice stesso auto-documentabile con una documentazione esterna minima. Successivamente, assumerei un altro sviluppatore esterno per eseguire una revisione del codice del proprio lavoro. Questo sviluppatore avrebbe "emulato" un nuovo sviluppatore e avrebbe cercato di capire cosa doveva fare l'applicazione e se lo stava facendo correttamente. Quindi produce un rapporto basato su quanto sia stato facile per lui. Questo potrebbe essere fatto periodicamente ogni poche settimane / mesi.

Penso che sia probabile che tu NON desideri la documentazione del codice dai programmatori.

Il motivo per cui affermi che ritieni di volere la documentazione è:

"I nuovi programmatori possono fare un buon lavoro di presa in consegna quando non ci sono report o documentazione, ecc."

Quindi la documentazione non è da leggere per te, non è un manuale per il prodotto, non ti dà alcun beneficio di per sé.

Se non ricevi nuovi programmatori durante la vita del tuo prodotto. Avrai pagato i tuoi programmatori per scrivere documenti che non vengono mai usati.

A mio parere, probabilmente i tuoi ipotetici nuovi programmatori non li leggeranno. I programmatori tendono a non leggere la documentazione del codice per una serie di motivi e questo è generalmente riconosciuto con le moderne metodologie di programmazione "agili".

Quindi io dico, non chiedere ai programmatori di documentare il loro codice.

Tuttavia! Ciò che DO deve documentare sono i tuoi requisiti e i test che hai eseguito per assicurarti che siano stati soddisfatti.

ad es.

Requirement 1: "when there is an error, make the button red"

ti servono questi perché i nuovi programmatori ipotetici non sapranno cosa il presunto codice debba fare.

I tuoi programmatori attuali comprendono il progetto, quindi quando lo dici

Requirement 2: 'Make the button blue'

Ricordano il tuo precedente requisito e renderanno il pulsante blu quando non è errato e rosso quando lo è.

I nuovi programmatori, tuttavia, non erano in giro quando hai chiesto il requisito 1. quindi lo renderanno blu tutto il tempo.

Dovrai ricordare tutti i requisiti e dirgli:

Requirement 2 : 'make the button blue, unless it is errored in which case it should be red'

È impossibile ricordare tutti i requisiti per i progetti anche di piccole dimensioni e, cosa peggiore, la combinazione di requisiti, vale a dire che lo stato rosso prevale sullo stato blu non viene mai effettivamente dichiarato. È qui che scrivi i tuoi test, avrai testato l'app che ha funzionato dopo il requisito 2 e scritto

"Tested normal page ok, tested error page ok"

Questo dirà ai nuovi sviluppatori che la pagina di errore è Supposto per avere un pulsante rosso, e non è un bug che deve essere corretto.

Ciò di cui hai bisogno per proteggersi dalla perdita è l'immagine di ciò che dovrebbe fare la tua applicazione. Questa è la cosa che esiste solo nei tuoi sviluppatori, al momento, ed è davvero qualcosa che solo tu puoi documentare.

Vuoi un documento di design di alto livello che descriva i grandi blocchi e le loro interazioni e quindi la progettazione funzionale che descriva come questi blocchi sono stati implementati. Leggi su UML per i concetti di progettazione principali (ma non farli distribuire documenti UML, per favore - vanno troppo nel dettaglio, vuoi solo le panoramiche)

Spesso la documentazione può essere sufficiente con un semplice documento di testo che descrive l'architettura generale, gli strumenti usati (e le versioni!) - quanto basta per consentire a un nuovo dev di comprendere i concetti e le ipotesi utilizzate che gli permetteranno di entrare nel codice per scopri i dettagli esatti dell'implementazione.

Puoi richiedere documentazione completa, ho lavorato in posti (polizia, governo) che hanno davvero bisogno di sapere esattamente come funziona qualcosa, e tale doc è una cosa bella da avere - ma diventa rapidamente più costoso da produrre, e penso che sarebbe eccessivo per le tue esigenze, quindi fai attenzione a non esagerare nella documentazione. C'è un punto debole tra nessuno, abbastanza per capire il prodotto e troppo.

Ciao, se ti capisco molto bene vuoi essere sicuro che quando i tuoi attuali programmatori non sono più lì per gestire il tuo sito web puoi assumere qualcun altro e sarà facile per loro scrivere e non reinventare la ruota. buono.

i buoni programmi sono di per sé una buona documentazione, mi dispiace che non ci sia una documentazione cartacea, ma nella codifica, potresti non saperlo ma i programmatori lo faranno. ricorda sempre loro di conservare la documentazione corretta. quando arriverà il nuovo programmatore, sa che troverà la documentazione.