Cos'è l'avversione alla documentazione del settore?

Non penso sia utile speculare sulle motivazioni di persone che non stanno adottando qualcosa che ritieni sia una buona pratica o che stanno continuando a fare qualcosa che ritieni una cattiva pratica. In questo business, le persone che rientrano in una o entrambe le categorie lontano sono più numerose di quelle che vedrai a occhi stretti, quindi smettila di farti impazzire.

Invece, concentrati sul problema e sulle possibili risoluzioni.

1. Scrivi una buona documentazione da te

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

Considera, invece, il lavoro per raggiungere l'obiettivo di scrivere una buona documentazione tu stesso e convincere la gente a usarlo. Ad esempio, se qualcuno del mio team mi chiede dove sia il codice sorgente per il Progetto A o quale sia la configurazione speciale del Progetto A, li indirizza alla pagina del wiki del Progetto A.

Se qualcuno mi chiede come scrivere una nuova implementazione di Factory F per personalizzare una cosa per il Client C, gli dico che si trova a pagina 10 della guida per gli sviluppatori.

La maggior parte degli sviluppatori odia fare domande che potrebbero far sembrare che non possano semplicemente "leggere il codice" ancor più di quanto non odiano leggere la documentazione, quindi dopo aver ricevuto risposte sufficienti di questa natura, andranno prima ai documenti.

2. Dimostra il valore della tua documentazione

Assicurati di cogliere ogni occasione per indicare dove la documentazione sta dimostrando il suo valore (o avrebbe, se usato). Cerca di essere sottile ed evita "te l'avevo detto", ma è perfettamente legittimo dire cose come

For future reference, the wiki page of this project has information about the branch of the core code that was created for ongoing support of release 2.1, so in future we can avoid having to do a full regression test if people who are maintaining released versions check the wiki before checking out the code.

o

I am so glad I wrote down the steps for doing Task T. I don't really care if no one else ever uses it--it's already saved me more time than what I spent writing it.

3. Ottieni la gestione a bordo

Dopo alcuni incidenti in cui la documentazione è in grado di risparmiare tempo e denaro, probabilmente noterai un netto "disgelo" verso la documentazione. Questo è il momento di premere il punto iniziando ad includere il tempo di documentazione nelle stime (anche se onestamente di solito aggiorno / creo documenti mentre sono in esecuzione lunghi processi, come compilazioni o check-in). Soprattutto se si tratta di un noleggio recente, è possibile che questo non venga messo in discussione, ma considerato come una nuova pratica che stai portando da un posto di lavoro precedente (che potrebbe essere).

Parola di cautela: alla maggior parte dei boss non piace che faccia le persone facciano qualsiasi cosa, specialmente cose non direttamente legate a un'attività fatturabile, quindi non aspettarti che questo supporto sia nel forma di un mandato. Invece, è più probabile che tu ti dia una possibilità relativamente libera di scrivere più documenti.

4. Incoraggia la documentazione quando la vedi

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

Se la tua squadra esegue revisioni del codice, questo è un momento in cui puoi inserire una o due parole per incoraggiare commenti positivi.

Thank you for documenting the workaround for bug B in Framework G. I didn't know about that, and I don't think I could have understood what you were doing without that in there.

Se hai qualcuno nel team che è entusiasta sulla documentazione, non fa male a coltivare quella persona andando a pranzo oa prendere un caffè e assicurandosi di offrire un po 'di validazione per contrastare lo scoraggiamento potrebbero non vedere più il resto del team.

Oltre a questo, non è davvero il tuo problema se non sei in 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 il trogolo.

Ci sono due fattori principali nella mia esperienza:

Scadenze

La maggior parte delle aziende sono talmente orientate alla data che il QA, il debito tecnologico e il design attuale vengono tagliati in modo tale che il project manager non sembri in cattive condizioni o colpisca una scadenza eccessivamente promettente per i clienti. In questo ambiente in cui viene ridotta anche la qualità funzionale, un investimento a lungo termine come la documentazione ha poche possibilità.

Modifica

Una best practice relativamente nuova per gli sviluppatori è quella di de-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 per mantenerle sincronizzate con poco beneficio. "Se il tuo codice è così difficile da leggere che hai bisogno di commenti, non sarebbe meglio spendere tempo per pulire il codice?"

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

La documentazione segue la stessa vena. Con l'adozione diffusa di agile, le persone riconoscono che i requisiti cambiano regolarmente. Con l'uso diffuso del refactoring, l'organizzazione del codice cambierà sostanzialmente. Perché passare il tempo a documentare tutto questo materiale che è destinato a cambiare? Il codice e i test dovrebbero fare un buon lavoro.

Ci sono una serie di fattori in gioco qui:

1. Il codice ben scritto è la sua documentazione. A parità di altre condizioni, è preferibile scrivere codice più chiaro che parli da solo, piuttosto che più documentazione. Fatelo e avrete bisogno di modificare meno la documentazione quando modificate quel codice.

2. Scrivere documentazione è probabilmente un'abilità diversa dalla scrittura del 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'uso di tali strumenti può essere più complicato e complicato della semplice scrittura manuale della documentazione, motivo per cui non si vedono questi strumenti ampiamente utilizzati.

4. Una buona documentazione richiede molto tempo ed è difficile farla bene. A parità di altre condizioni, può essere più utile scrivere un nuovo codice piuttosto che scrivere documentazione per codice già esistente.

5. Quando il codice cambia, devi anche cambiare la documentazione. Minore è la documentazione, meno è necessario modificarlo.

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

Elefante nella stanza: i programmatori non sono (necessariamente) scrittori. Né sono necessariamente suscettibili di arricchire le loro implementazioni con gli scrittori tecnici. Secondo Elefante nella stanza: gli scrittori tecnici non sono in genere in grado di fornire dettagli utili per gli sviluppatori futuri (anche se gli sviluppatori si degnerebbero di spiegarglielo).

Un sistema complesso può diventare quasi imperscrutabile nel tempo senza una documentazione adeguata. Il codice diventa meno prezioso inversamente proporzionale alla sua scrutabilità [sic]. Risolto, la gestione assume Software Engineer in grado di leggere codice e dettagli coassiali dagli sviluppatori, lo paga a un tasso di sviluppo e gli impone di documentare e mantenere la documentazione. Questo autore può leggere il codice e saprà quali domande porre e riempirà i dettagli secondo necessità. Proprio come hai un dipartimento QA, hai un dipartimento di documentazione interno.

Il codice diventerà più prezioso, dato che è possibile acquistarlo in licenza a una terza parte (perché può capirlo), il codice può essere più facilmente controllato e migliorato / rielaborato, si avrà un riutilizzo del codice migliore anche dove puoi facilmente calcolare le versioni più leggere del tuo software e sarai in grado di introdurre nuovi sviluppatori più facilmente nel progetto, i tuoi tecnici di supporto adoreranno lavorare per te.

Questo non succederà mai.

More importantly, how do I convince them that writing docs will save us time and frustration in the future?

Lo fa?

Esistono due tipi di documentazione:

Documentazione utile

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

Documentazione inutile

Documentazione che cambia spesso, poche persone sono interessate a questo e nessuno sa dove trovarlo. Come lo stato corrente di una funzionalità implementata. O documenti requisito in una parola doc nascosti da qualche parte in SVN, aggiornati 3 anni fa. Questa documentazione richiederà tempo per scrivere e il tempo di scoprire che è sbagliato in seguito. Non puoi fare affidamento su questo tipo di documentazione. È inutile. Si perde tempo.

I programmatori non amano scrivere o leggere documentazione inutile. Ma se puoi mostrare loro la documentazione che è utile, la scriveranno. Abbiamo avuto successo con esso nel mio ultimo progetto quando ho introdotto un Wiki in cui potevamo 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. Ci sono un certo numero di classi di documentazione da considerare:

Documentazione prodotto / versione

Questo è tutto ciò che esce con il tuo prodotto finito. Questo è più di semplici manuali, questo è README, registri di modifiche, HOW-TO e simili. In teoria, puoi scappare senza scriverli, ma ti ritroverai con un prodotto che le persone non vogliono utilizzare o un carico di supporto che è inutilmente costoso.

Documentazione API

Questo descrive qualcosa che dovrebbe essere relativamente statico. Dal momento che numerosi consumatori potrebbero essere codificati per la tua API, dovrebbe essere abbastanza sufficientemente stabile da suggerire che alcuni prosa descrivono come utilizzarlo. 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 divenire, al momento. Quando ho iniziato a scrivere codice professionalmente, i commenti erano un sine qua non quando si trattava di scrivere codice. Ora, la moda è scrivere un codice così chiaro, i commenti non sono necessari. Mi azzardo a pensare che questo sia, in parte, dovuto al fatto che molti linguaggi moderni sono scritti ad un livello molto più alto ed è molto più semplice scrivere codice leggibile in Java, JavaScript, Ruby, ecc. Di quanto non fosse nell'assembler , C, FORTRAN, ecc. Quindi, i commenti avevano un valore molto più grande.

Continuo a credere che ci sia un valore nei commenti che descrivono intenzione di una sezione di codice, o alcuni dettagli sul perché un determinato algoritmo è stato scelto su uno più ovvio (per evitare un eccesso di zelo refactoring fiends da 'fixing' di codice che in realtà non ha bisogno di essere risolto).

Sfortunatamente, c'è un sacco di 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, è quella che dovrebbe essere fatta a livello di squadra. Per i livelli più alti di astrazione, può essere più sensato avere qualcuno, oltre agli sviluppatori, per farlo. Per quanto riguarda la documentazione a livello di commenti, è necessario concordare insieme un accordo sullo scopo e l'intento dei commenti, in particolare nei team di abilità e esperienza miste. Non va bene avere sviluppatori senior che scrivono codice che gli sviluppatori più giovani non possono avvicinare. Alcuni documenti ben posizionati e ben scritti possono consentire a una squadra di operare in modo molto più efficace

Ecco i miei due centesimi.

1. Il Manifesto Agile afferma "Software di lavoro su una documentazione completa" e non tutti si leggono per raggiungere "Cioè, mentre c'è valore negli articoli a destra, noi valuta di più gli elementi a sinistra. "

2. Purtroppo è comune al link e la documentazione non funziona con questo modello (Esce da sync).

3. L'industria dello sviluppo del software non è ben regolata. Non esiste alcun requisito legale per scrivere documentazione.

4. Il codice di autocertificazione è la tendenza attuale.

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

La documentazione richiede tempo e ho il sospetto che molti sviluppatori abbiano avuto troppi run-in con documentazione che è stata peggio che inutile. Loro hanno l'idea che non solo documenteranno i problemi dal loro manager (lo stesso che continua a tagliare la parte QA del programma), ma non aiuterà nessuno, compresi loro.

Un po 'di documentazione a metà decente è un investimento per il futuro. Se non ti interessa il futuro (perché non pensi oltre il prossimo stipendio, o perché pensi che non sarà il tuo problema), allora il pensiero di fare la documentazione è estremamente doloroso.

Molte altre risposte sottolineano il fatto che esistono almeno due tipi di documentazione: un set per altri sviluppatori e un set diverso per gli utenti finali. A seconda dell'ambiente, potrebbe essere necessaria anche una documentazione aggiuntiva per amministratori di sistema, installatori e personale dell'help desk. Ogni pubblico di destinazione 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 competenze richiesto per produrre una buona documentazione è antitetico alle competenze richieste per produrre un buon codice.

Un buon writer di documentazione può comunicare in più lingue: la lingua degli utenti, la lingua di gestione, la lingua del personale di supporto, la lingua degli sviluppatori. È compito di uno scrittore di documentazione capire cosa comunica un codificatore e tradurlo in una forma comprensibile a tutti gli altri gruppi.

Quando ti aspetti che i programmatori sviluppino l'abilità necessaria per diventare buoni comunicatori (scritti o meno), la quantità di tempo impiegato per perfezionare il set di abilità primarie (codifica!) è diminuita. Più lontano si ottiene dalla sua zona di comfort (codifica e comunicazione con altri codificatori), più tempo ed energia saranno necessari per svolgere bene il compito. 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 sul codice in linea) è preferibile 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 dei parametri. Non può spiegare la semantica o l'intenzione esatta dell'autore: hai bisogno di commenti.

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

La documentazione non viene eseguita come il codice. Di conseguenza spesso non esistono loop di feedback efficaci per verificare che la documentazione sia a posto e completa. Questa è la stessa ragione 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 quanto più leggibile possibile e di utilizzare i test unitari per documentare l'utilizzo per altri sviluppatori. Penso che questo sia parte dell'idea più grande di avere la tua API come un modulo che può essere esplorato e scoperto. 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 odiosamente poca documentazione: non possono digitare. Se hai qualche approssimazione del sistema a 10 dita, tendi a scrivere più documentazione solo perché è facile. Ma se sei bloccato con la caccia e beccando sei perso. Se dovessi essere responsabile dell'assunzione, questo è qualcosa che controllerei.

Le persone che non amano leggere la documentazione non amano scrivere la documentazione. Un sacco di 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ù inclini a scrivere qualcosa.

Quando ho iniziato il mio attuale lavoro e ho preso il controllo di un progetto hardware + software da persone che in precedenza ci lavoravano, mi è stato fornito un centinaio di documenti di parole che descrivevano il sistema. Ci sono voluti giorni per produrre. L'ho guardato forse due volte. Nonostante le enormi quantità di informazioni in esso contenute, raramente ha risposto alle domande reali che avevo sul sistema, e anche quando è stato eseguito, era più veloce osservare il codice.

Dopo un numero sufficiente di esperienze del genere, inizi a pensare, perché preoccuparsi? Perché passare il tempo a rispondere alle domande che le persone non hanno mai chiesto? Inizi a realizzare quanto sia davvero difficile prevedere quali informazioni le persone cercheranno nella documentazione; è inevitabilmente pieno di fatti che risultano inutili, poco chiari o ovvi e privi delle risposte alle domande più urgenti. Ricorda, produrre documentazione utile è uno sforzo per predire il comportamento umano. Proprio come è improbabile che un design dell'interfaccia utente abbia successo prima che abbia attraversato più iterazioni di testing e debug, quindi è ingenuo pensare che sia possibile scrivere una documentazione utile basandosi solo sulle aspettative di come le persone interpreteranno il sistema e su cosa ruolo la documentazione e il suo linguaggio giocheranno in quella interpretazione.

Tendo a pensare che la maggior parte della pressione per scrivere documentazione deriva dal fatto che si tratta di un compito sgradevole e le persone si sentono in colpa a fare faccende spiacevoli ("Non hai mangiato i tuoi studi di filato!").

TUTTAVIA

Non penso che la documentazione sia, in tutti i modi, senza speranza. Penso che sia senza speranza soprattutto quando le persone considerano la documentazione come un onere aggiuntivo che deve essere soddisfatto prima che un lavoro sia finito, come un ultimo pezzo di lavoro di pulizia da sfogliare e come una scatola da controllare. La documentazione è qualcosa che dovresti lavorare sugli aspetti della tua giornata che fai sempre comunque. Penso che l'e-mail sia un ottimo modo per fare documentazione. Quando aggiungi una nuova funzione, scrivi a poche persone una rapida email che dice di cosa si tratta. Quando disegni un nuovo schema, genera un PDF e invialo a chiunque sia interessato. I vantaggi dell'email sono:

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

2. L'email esiste nel contesto, circondata da altre e-mail che parlano della funzione e delle relative funzioni e di qualsiasi altra cosa che stava succedendo in quel momento.

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

4. L'email consente alle persone che si preoccupano di porre domande subito,

5. L'email è estremamente ricercabile, perché le persone lo usano per tutto e i client di posta hanno avanzato un bel po 'nel corso degli anni.

6. Se si trova in un'email, almeno un'altra persona sa dove trovarlo.

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