Qual è l'avversione alla documentazione nel settore?

Sembra esserci un'avversione nello scrivere anche la documentazione più elementare. I nostri README di progetto sono relativamente spogli. Non ci sono nemmeno elenchi aggiornati di dipendenze nei documenti.

C'è qualcosa di cui non sono a conoscenza nel settore che non piace ai programmatori scrivere documenti? Posso scrivere paragrafi di documenti se necessario, quindi perché altri sono così contrari?

Ancora più importante, come posso convincerli che scrivere documenti ci farà risparmiare tempo e frustrazione in futuro?

Non credo sia utile speculare sulle motivazioni delle persone che non adottano qualcosa che ritieni sia una buona pratica o che continuano a fare qualcosa che vedi come cattiva pratica. In questo settore, le persone che rientrano in una o entrambe queste categorie supereranno di gran lunga quelle con cui vedrai gli occhi, quindi smetti di farti impazzire.

Concentrati invece sul problema e sulle possibili risoluzioni.

1. Scrivi tu stesso una buona documentazione

Potrebbe non essere realistico aspettarsi che tutti i membri del tuo team indirizzino i loro sforzi verso le cose che vedi come un problema. Ciò è particolarmente vero se sei un nuovo arrivato relativamente alla squadra. Mi azzarderei a indovinarlo, perché se fossi un membro fondatore del team, sembra molto probabile che avresti già risolto questo problema all'inizio.

Prendi invece in considerazione l'obiettivo di scrivere te stesso una buona documentazione e convincere le persone a usarla. Ad esempio, se qualcuno nel mio team mi chiede dove sia il codice sorgente per il Progetto A o quale configurazione speciale abbia bisogno del Progetto A, li indico alla pagina wiki del Progetto A.

Se qualcuno mi chiede come scrivere una nuova implementazione di Factory F per personalizzare qualcosa per il Cliente C, dico loro che è a pagina 10 della guida per gli sviluppatori.

La maggior parte degli sviluppatori odia porre domande che potrebbero far sembrare che non possano semplicemente "leggere il codice" anche più di quanto odiano leggere la documentazione, quindi dopo sufficienti risposte di questo tipo, andranno prima ai documenti.

2. Dimostra il valore della tua documentazione

Assicurati di cogliere ogni opportunità per sottolineare dove la documentazione sta dimostrando il suo valore (o avrebbe, se utilizzato). Cerca di essere discreto ed evita "Te l'avevo detto", ma è perfettamente legittimo dire cose del genere

Per riferimento futuro, la pagina wiki di questo progetto contiene informazioni sul ramo del codice core creato per il supporto continuo della versione 2.1, quindi in futuro possiamo evitare di dover fare un test di regressione completo se le persone che mantengono le versioni rilasciate controllano il wiki prima di controllare il codice.

o

Sono così felice di aver scritto i passaggi per svolgere l'attività T. Non mi interessa davvero se nessun altro lo usa mai - mi ha già risparmiato più tempo di quello che ho passato a scriverlo.

3. Ottieni la gestione a bordo

Dopo alcuni incidenti in cui avere documentazione sta dimostrando un notevole risparmio di tempo / denaro, probabilmente noterete un distinto "disgelo" verso la documentazione. Questo è il momento di insistere sul punto iniziando a includere il tempo di documentazione nelle tue stime (anche se onestamente di solito aggiorno / creo documenti mentre sono in esecuzione processi lunghi, come compilazioni o check-in). Soprattutto se si tratta di un noleggio recente, è possibile che questo non venga messo in discussione, ma invece visto come una nuova pratica che stai introducendo da un posto di lavoro precedente (che potrebbe benissimo essere).

Avvertenza: alla maggior parte dei capi non piace fare in modo che le persone facciano qualsiasi cosa, in particolare cose non direttamente legate a un'attività fatturabile, quindi non aspettatevi che questo supporto abbia la forma di un mandato. Invece, è più probabile che ti dia libero sfogo per scrivere più documenti.

4. Incoraggia la documentazione quando la vedi

Forse parte del motivo per cui le persone non scrivono documenti tutte le volte che dovrebbero è che non sentono nessuno che lo sta leggendo. Quindi, quando vedi qualcosa che ti piace, assicurati almeno di dire che eri contento che fosse disponibile.

Se il tuo team esegue revisioni del codice, questo è un momento in cui puoi inserire una o due parole sottili per incoraggiare buoni commenti.

Grazie per aver documentato la soluzione alternativa per il bug B nel Framework G. Non lo sapevo, e non credo che avrei potuto capire cosa stavi facendo senza quello.

Se hai qualcuno nella squadra che è davvero entusiasta della documentazione, non fa male coltivare quella persona andando a pranzo o al caffè e assicurandoti di offrire una piccola convalida per contrastare lo scoraggiamento che potrebbero avere dal vedere il resto della squadra non valuta tanto la documentazione.

Oltre a ciò, non è davvero un tuo problema se non sei in una posizione di comando o di gestione. Puoi condurre un cavallo all'acqua, ma non puoi farlo bere. Se non è il tuo cavallo, potresti non essere felice che abbia sete, ma tutto ciò che puoi fare è riempire la vasca.

Ci sono due fattori principali nella mia esperienza:

scadenze

La maggior parte delle aziende sono talmente determinate dalla data che il QA, il debito tecnologico e il design attuale vengono tagliati proprio in modo che il responsabile del progetto non sembri cattivo o non raggiunga una scadenza assurda e troppo promessa per i clienti. In questo ambiente in cui anche la qualità funzionale viene ridotta, un investimento a lungo termine come la documentazione ha poche possibilità.

Modificare

Una best practice relativamente nuova per gli sviluppatori è di non enfatizzare i commenti. L'idea è che mantenere le informazioni in due punti (il codice [compresi i test] e i commenti intorno al codice) porta a un sacco di spese generali nel mantenerle sincronizzate per un piccolo vantaggio. "Se il tuo codice è così difficile da leggere che hai bisogno di commenti, non sarebbe meglio passare il tempo a ripulirlo?"

Personalmente non guarderò più nemmeno i commenti. Il codice non può mentire.

La documentazione segue la stessa vena. Con l'adozione diffusa di agili, le persone riconoscono che i requisiti cambiano regolarmente. Con l'uso diffuso del refactoring, l'organizzazione del codice cambierà sostanzialmente. Perché perdere tempo a documentare tutte queste cose che sono destinate a cambiare? Il codice e i test dovrebbero fare abbastanza bene.

Ci sono una serie di fattori in gioco qui:

1. Il codice ben scritto è la sua stessa documentazione. A parità di altre condizioni, è meglio scrivere un codice più chiaro che parli da solo, piuttosto che più documentazione. Fallo e dovrai modificare meno documentazione quando cambi quel codice.

2. Scrivere documentazione è probabilmente un'abilità diversa rispetto alla scrittura di codice. Alcuni sviluppatori di software sono più bravi di altri. Alcuni sono molto più bravi a scrivere codice che a scrivere documentazione.

3. La documentazione dovrebbe essere scritta solo una volta , non due volte (una volta nel codice sorgente e di nuovo nella guida del programmatore). Ecco perché abbiamo cose come commenti XML e generatori di documentazione. Sfortunatamente, l'utilizzo di tali strumenti può essere più complicato e complicato della semplice scrittura manuale della documentazione, motivo per cui non si vedono quegli strumenti ampiamente utilizzati.

4. Una buona documentazione richiede tempo e difficile da fare bene. A parità di altre condizioni, può esserci più valore nella scrittura di un nuovo codice che nella scrittura di documentazione per codice già esistente.

5. Quando il codice cambia, devi anche cambiare la documentazione. Meno documentazione c'è, meno deve essere cambiata.

6. Nessuno legge comunque la documentazione, quindi perché preoccuparsi?

Elefante nella stanza: i programmatori non sono (necessariamente) scrittori. Né sono necessariamente suscettibili di dare le loro implementazioni agli scrittori tecnici. Secondo elefante nella stanza: gli scrittori tecnici non sono generalmente in grado di mettere a punto dettagli utili per i futuri sviluppatori (anche se gli sviluppatori si degnano di spiegarglieli).

Un sistema complesso può diventare quasi imperscrutabile nel tempo senza un'adeguata documentazione. Il codice diventa inversamente meno prezioso proporzionalmente alla sua scrutabilità [sic]. Risolto, il management assume l'ingegnere del software che può leggere codice e dettagli coassiali dagli sviluppatori, lo paga a una tariffa di sviluppo e gli impone di documentare e conservare la documentazione. Questo autore può leggere il codice e saprà quali domande porre e riempirà i dettagli se necessario. Proprio come hai un dipartimento di controllo qualità, hai un dipartimento di documentazione interna.

Il codice diventerà più prezioso, poiché puoi concederlo in licenza a una terza parte (perché lui può capirlo), il codice può essere verificato e migliorato / rielaborato più facilmente, avrai un migliore riutilizzo del codice anche dove puoi facilmente fattorizza versioni più leggere del tuo software e sarai in grado di introdurre più facilmente nuovi sviluppatori nel progetto, i tuoi tecnici di supporto adoreranno lavorare per te.

Questo non accadrà mai.

Ancora più importante, come posso convincerli che scrivere documenti ci farà risparmiare tempo e frustrazione in futuro?

Lo fa?

Esistono due tipi di documentazione:

Documentazione utile

Documenta come utilizzare un prodotto finito, un'API, quali indirizzi IP o nomi URL hanno i nostri server, ecc. Fondamentalmente, tutto ciò che viene utilizzato pesantemente e su base giornaliera. Le informazioni errate verranno scoperte rapidamente e saranno corrette. Deve essere trovato facile e facile da modificare (ad esempio Wiki online).

Documentazione inutile

Documentazione che cambia spesso, pochissime persone ne sono interessate e nessuno sa dove trovarla. Come lo stato corrente di una funzionalità implementata. O i documenti dei requisiti in un documento word nascosto da qualche parte in SVN, aggiornato 3 anni fa. Questa documentazione richiederà tempo per scrivere e tempo per scoprire che è sbagliato in seguito. Non puoi fare affidamento su questo tipo di documentazione. È inutile. Perde tempo.

Ai programmatori non piace scrivere o leggere documentazione inutile. Ma se puoi mostrare loro la documentazione utile, la scriveranno. Abbiamo avuto successo con esso nel mio ultimo progetto quando ho introdotto un Wiki in cui potremmo scrivere tutte le informazioni di cui abbiamo bisogno spesso.

Direi che la ragione principale è la mancanza di volontà e la mancanza di comprensione della funzione della documentazione. Esistono diverse classi di documentazione da considerare:

Documentazione prodotto / rilascio

Questo è tutto ciò che esce con il tuo prodotto 'finito'. Non si tratta solo di manuali, sono README, registri delle modifiche, HOW-TO e simili. In teoria, puoi evitare di non scriverli, ma finisci con un prodotto che le persone non vogliono usare o con un onere di supporto che è inutilmente costoso.

Documentazione API

Questo descrive qualcosa che dovrebbe essere relativamente statico. Dal momento che numerosi utenti potrebbero codificare la tua API, dovrebbe essere sufficientemente stabile da avere un valore in qualche prosa che descriva come usarla. Descrivere quali parametri sono supportati, quale può essere il valore restituito e quali errori possono essere generati consentirà ad altri utenti di comprendere la tua API al giusto livello di astrazione - l'interfaccia ( non l'implementazione).

Commenti sul codice

L'opinione del settore sui commenti sembra essere in evoluzione, al momento. Quando ho iniziato a scrivere codice in modo professionale, i commenti erano una condizione sine qua non quando si trattava di scrivere codice. Ora, la moda è scrivere un codice così chiaro, i commenti non sono necessari. Immagino che questo sia, in parte, dovuto al fatto che molti linguaggi moderni sono scritti a un livello molto più alto ed è molto più facile scrivere codice leggibile in Java, JavaScript, Ruby, ecc. Che in assemblatore , C, FORTRAN, ecc. Pertanto, i commenti avevano un valore molto maggiore.

Continuo a credere che nei commenti vi sia valore che descriva l' intenzione di una sezione di codice, o alcuni dettagli sul perché un certo algoritmo è stato scelto su uno più ovvio (per evitare demoni di refactoring troppo zelanti dal codice di "fissaggio" che non " in realtà deve essere riparato).

Sfortunatamente, c'è molto egoismo, razionalizzazione e auto-illusione coinvolti nelle decisioni dei programmatori di non documentare. La realtà è che, come il codice, il pubblico principale per la documentazione sono le altre persone. Pertanto, le decisioni di scrivere (o non scrivere) la documentazione, a qualsiasi livello, devono essere prese a livello di squadra. Per i livelli più alti di astrazione, può avere più senso avere qualcuno, diverso dagli sviluppatori, per farlo. Per quanto riguarda la documentazione a livello di commento, raggiungere un accordo sullo scopo e l'intento dei commenti dovrebbe essere concordato insieme, specialmente in team misti di esperienza ed esperienza. Non va bene avere sviluppatori senior che scrivono codice a cui gli sviluppatori junior non possono avvicinarsi. Una documentazione ben posizionata e ben scritta può consentire a un team di operare in modo molto più efficace

Ecco i miei due centesimi.

1. Il Manifesto Agile afferma "Software funzionante su documentazione completa" e non tutti leggono per raggiungere "Cioè, mentre c'è valore negli oggetti a destra, noi valutiamo di più gli oggetti a sinistra".

2. Purtroppo è comune a https://en.wikipedia.org/wiki/Code_and_fix e la documentazione non funziona con questo modello (si sincronizza).

3. L'industria dello sviluppo del software non è ben regolata. Non vi è alcun obbligo legale di scrivere documentazione.

4. Il codice auto-documentante è la tendenza attuale.

Detto questo, penso che ci sia molta buona documentazione là fuori.

La documentazione richiede tempo e sospetto che molti sviluppatori abbiano avuto troppi run-in con documentazione che era peggio che inutile. Hanno l'idea che non solo i documenti li porteranno problemi dal loro manager (lo stesso ragazzo che continua a tagliare la parte QA del programma), ma non aiuterà nessuno, compresi loro.

Qualsiasi pezzo di documentazione decente è un investimento per il futuro. Se non ti interessa il futuro (perché non pensi al di là della prossima busta paga, o perché pensi che non sarà il tuo problema), il pensiero di fare la documentazione è estremamente doloroso.

Molte delle altre risposte superano il fatto che esistono almeno due tipi di documentazione: una per altri sviluppatori e una diversa per gli utenti finali. A seconda del proprio ambiente, potrebbe anche essere necessaria ulteriore documentazione per amministratori di sistema, installatori e personale dell'help desk. Ogni pubblico target ha esigenze e livelli di comprensione diversi.

Considera lo sviluppatore (stereo-) tipico: è un programmatore per scelta. Ha scelto una carriera fuori dal pubblico e trascorre lunghe ore dietro una tastiera che comunica principalmente con se stesso. Il processo di documentazione è una forma di comunicazione e il set di abilità richiesto per produrre una buona documentazione è antitetico alle capacità richieste per produrre un buon codice.

Un buon scrittore di documentazione può comunicare in più lingue: la lingua degli utenti, la lingua della direzione, la lingua del personale di supporto, la lingua degli sviluppatori. È compito di uno scrittore di documentazione comprendere ciò che comunica un programmatore e tradurlo in una forma comprensibile a tutti gli altri gruppi.

Quando ti aspetti che i programmatori sviluppino le abilità necessarie per diventare buoni comunicatori (scritti o meno), il tempo trascorso a perfezionare il set di abilità primarie (codifica!) Diminuisce. Più si allontana dalla sua zona di comfort (codifica e comunica con altri programmatori), maggiore sarà il tempo e l'energia necessari per eseguire bene l'attività. Puoi ragionevolmente aspettarti che un programmatore professionista desideri concentrarsi principalmente sulle sue competenze chiave, a spese di tutti gli altri.

Per questo motivo, la documentazione (ad eccezione dei commenti di codice in linea) è meglio lasciare ai comunicatori, non ai programmatori.

La lettura del codice mostra come funziona. Non può spiegare perché : hai bisogno di commenti.

La lettura del codice mostra il nome di un metodo e i tipi di parametri. Non può spiegare la semantica o l'intenzione esatta dell'autore: hai bisogno di commenti.

I commenti non sostituiscono la lettura del codice, ma vengono aggiunti ad esso.

La documentazione non viene eseguita come lo è il codice. Di conseguenza, spesso non sono disponibili cicli di feedback efficaci per verificare che la documentazione sia a posto e sia completa. Questo è lo stesso motivo per cui i commenti sul codice tendono a marcire.

Donald Knuth ha promosso Literate Programming come un modo per migliorare la qualità del software, scrivendo efficacemente la documentazione con il codice. Ho visto alcuni progetti che hanno utilizzato questo approccio in modo abbastanza efficace.

Personalmente cerco di attenermi alla tendenza moderna di mantenere l'API pubblica del tuo codice il più leggibile possibile e di utilizzare unit test per documentare l'utilizzo per altri sviluppatori. Penso che questo sia parte dell'idea più grande di avere la tua API in una forma che può essere esplorata e scoperta. Penso che questo approccio sia parte di ciò che HATEOAS cerca di raggiungere con i servizi web.

Un punto minore, ma che sembra essere importante con alcuni sviluppatori che scrivono una documentazione odiosamente scarsa: non possono scrivere. Se si dispone di un'approssimazione del sistema a 10 dita, si tende a scrivere più documentazione solo perché è facile. Ma se sei bloccato con la caccia e il becco ti perdi. Se sarei responsabile per l'assunzione questo è in realtà qualcosa che controllerei.

Le persone a cui non piace leggere la documentazione non amano scrivere la documentazione. Molti programmatori faranno tutto il possibile per evitare di leggere a fondo un documento.

Non concentrarti sulla scrittura, concentrati sulla lettura. Quando i programmatori leggono la documentazione e ne assimilano le cose, vedranno il valore e saranno molto più propensi a scriverne.

Quando ho iniziato il mio attuale lavoro e ho assunto un progetto hardware + software da parte delle persone che ci avevano lavorato in precedenza, mi è stato dato un documento di centinaia di pagine che descriveva il sistema. Ci sono voluti giorni per produrlo. L'ho guardato forse due volte. Nonostante l'enorme quantità di informazioni presenti, raramente rispondeva alle domande reali che avevo sul sistema e, anche quando lo faceva, era più veloce guardare il codice.

Dopo abbastanza esperienze del genere, inizi a pensare, perché preoccuparsi? Perché passare il tempo a rispondere alle domande che la gente non ha mai posto? Inizi a capire quanto sia veramente difficile prevedere quali informazioni le persone cercheranno nella documentazione; è inevitabilmente pieno di fatti che si rivelano inutili, poco chiari o ovvi e privi delle risposte alle domande più urgenti. Ricorda, produrre documentazione utile è uno sforzo nel predire il comportamento umano. Proprio come è improbabile che la progettazione di un'interfaccia utente abbia successo prima che abbia attraversato più iterazioni di test e debug, è ingenuo pensare che sia possibile scrivere una documentazione utile basata solo sulle aspettative di come le persone interpreteranno il sistema e cosa ruolo che avrà la documentazione e il suo linguaggio in tale interpretazione.

Tendo a pensare che la maggior parte della pressione per scrivere la documentazione derivi dal fatto che si tratta di una faccenda spiacevole e alla gente piace sentirsi in colpa a vicenda facendo spiacevoli faccende ("Non hai mangiato il tuo filboid studge!").

PERÒ

Non credo che la documentazione sia, in tutti i modi, senza speranza. Penso che sia senza speranza soprattutto quando le persone vedono la documentazione come questo onere aggiuntivo che deve essere soddisfatto prima che un lavoro sia finito, come un ultimo pezzo di lavoro di pulizia da affrettarsi e come una scatola da controllare. La documentazione è qualcosa su cui dovresti lavorare sugli aspetti della tua giornata che fai sempre comunque. Penso che l'e-mail sia un modo particolarmente valido per fare documentazione. Quando aggiungi una nuova funzionalità, scrivi ad alcune persone una veloce email dicendo di cosa si tratta. Quando si disegna un nuovo schema, generare un PDF e inviarlo a chiunque possa essere interessato. I vantaggi dell'email sono:

1. Le persone di solito controllano la posta elettronica, mentre nessuno guadagna una cartella chiamata "doc".

2. La posta elettronica esiste nel contesto, circondata da altre e-mail che discutono della funzione e delle funzionalità correlate e di qualsiasi altra cosa succedesse in quel momento.

3. L'email è breve e mirata e ha una riga dell'oggetto.

4. La posta elettronica consente alle persone che si preoccupano di porre immediatamente domande,

5. La posta elettronica è altamente ricercabile, perché la gente la usa per tutto e i client di posta elettronica sono progrediti un po 'nel corso degli anni.

6. Se si trova in un'e-mail, almeno un'altra persona sa dove trovarla.

In teoria dovrebbe sembrare che anche i commenti in codice debbano essere "aspetti della tua giornata che fai sempre comunque", ma ad essere sincero, non ho mai letto commenti in codice. Non sono sicuro del perché, ma non sono molto utili, forse perché c'è una mancanza di contesto, che l'email risolve.