I documenti dovrebbero essere scritti dai programmatori esperti?

Question

Penso sempre che il documento sia davvero importante per un progetto e una squadra e dovrebbe essere scritto regolarmente e dettagliatamente. Può far andare le cose in parallelo senza chiedere sempre ai programmatori esperti qua e là. Ma in realtà trovo che molti sviluppatori (anche i leader) non prestino molta attenzione ai documenti e li prendano per scontati, il che mi fa stare male.

Quindi il mio atteggiamento nei confronti dei documenti è corretto? I documenti sono davvero importanti? Come dovrei convincere il capo squadra a porre maggiore attenzione ai documenti?

Se i documenti sono importanti, la seconda domanda sorge. Chi dovrebbe scrivere i documenti? IMO, dovrebbero essere scritti dagli esperti programmatori come il creatore del framework (se usiamo il nostro framework), le parti importanti del progetto (come lo schema db, l'intera architettura, ecc.) E altro ancora.

I vantaggi sono ovvi, come aiutare l'uomo fresco, aiutare a mantenere e altro ancora.

Quindi, secondo la mia opinione, i programmatori qualificati (la definizione qui può essere diversa) dovrebbero prestare maggiore attenzione alla scrittura dei documenti rispetto alla scrittura del codice dopo che l'infrastruttura è stata eseguita.

Ho ragione su questo punto?

Grazie per la condivisione di queste domande.

Answer 1

Il tuo gruppo dovrebbe creare un processo di sviluppo software che definisca il modo in cui sviluppi i tuoi prodotti software. Parte di quel processo definirà i documenti da scrivere e, nella mia esperienza, tutti i membri del team di sviluppo condividono il processo di documentazione: può (e dovrebbe) essere un processo di apprendimento.

il processo di sviluppo del software dovrebbe definire altri argomenti pure, come ad esempio le revisioni del codice, unit testing, la gestione della configurazione, ecc

Ci sono molti esempi di processi, da molto chiaro al molto pesante sul web.

Answer 2

Non hai torto, ma il fatto è che la documentazione non guadagna. Se non altro, una scarsa documentazione può aumentare le entrate perché hai assicurato che i clienti avranno bisogno del tuo contratto di assistenza.

documentazione è anche un dolore perché in teoria si suppone essere fatto prima sviluppo, ma in realtà le cose cambiano così vale veramente la pena solo la creazione/aggiornamento dopo una major release di versione.

Idealmente, l'autore dovrebbe essere l'analista aziendale, non lo sviluppatore.

Answer 3

Le domande importanti da porre su qualsiasi documentazione potenziale è qual è l'obiettivo, l'utilizzo previsto e la frequenza prevista di utilizzo della documentazione? Hai menzionato come aiutare un uomo nuovo, ma in pratica, stai leggendo la documentazione più velocemente ed efficacemente ottenendo una soluzione da un altro sviluppatore? Una procedura dettagliata richiede tempo all'altro sviluppatore, ma probabilmente molto meno tempo rispetto alla scrittura di un documento.

La documentazione con un business case forte e ROI su opzioni alternative ha senso creare, ma ci sono probabilmente meno casi di ciò che si immagina e la creazione di documentazione senza una risposta chiara alle mie domande iniziali garantirà che non si ottenere il ROI per questo.

Answer 4

Penso che spetti a ciascuna squadra, ma molte volte, i programmatori non sono esperti nella documentazione scritta. Questo è il motivo per cui ci sono persone come gli scrittori tecnici. I programmatori dovrebbero essere coinvolti in ogni fase dato che sono gli esperti in materia, ma gli scrittori dovrebbero scrivere.

Answer 5

Sono disponibili diverse tipologie di documentazione, uno di loro è la vostra responsabilità:

Documento ogni funzione, di classe, la struttura, membro come si completa

Idealmente, si farlo in un modo che consente l'estrazione automatica della documentazione sorgente (ad es. Doxygen). Assicurati di farlo mentre vai.

Per quanto riguarda la documentazione per il cliente va, le mie convinzioni sono:

• Ogni società di sviluppo dovrebbe impiegare tester
• Tester dovrebbero contribuire pesantemente al processo di documentazione

Sono stato con le aziende che semplicemente non pagherà per intero il per il prodotto finale a meno che non sia fornito con una documentazione completa e completa. Il 10% viene solitamente trattenuto solo per garantire che l'appaltatore abbia incentivi a consegnare tutti i materiali.

Per quanto riguarda i tester, sono davvero i tuoi migliori amici (o dovrebbero essere). Sono le persone che sanno come funziona il tuo software quasi come te. E sì, sono d'accordo, dovresti avere almeno un profilo di una funzionalità di programma, questo ti impedisce di andare avanti con le tangenti di "valore aggiunto". Ha senso lasciare che siano i tester a riempirlo, quindi chiedi agli sviluppatori di controllarlo per verificarne la precisione.

Potresti persino trovarti "No no no .. non funziona in questo modo ... i tester hanno sbagliato ...", quindi accendi l'app per capire che l'hanno presa giusto :) In questo aspetto, è anche utile per il processo di controllo qualità.

Answer 6

Un altro modo di guardare la documentazione è a fini CYA. Se hai mai avuto la sfortuna di essere in un progetto, in cui la leadership non genera documentazione, la colpa per il codice errato può andare a te. A meno che tu non ti protegga con la documentazione.

Answer 7

La persona che parla meglio la lingua del cliente è la persona che dovrebbe scrivere la documentazione, anche se non è la persona che meglio capisce il prodotto. Dovrebbero conferire con la persona che comprende meglio il prodotto, ma la documentazione non riguarda la capacità di codifica; si tratta di comunicazione.

Se non sei bravo a comunicare, non importa quanto bene conosci il tuo prodotto, la tua documentazione sarà inutile.