Perché così tante librerie non hanno / scarsa documentazione? [chiuso]

Allo stesso modo di Come possono avere successo i progetti open source senza documentazione sulla loro progettazione o architettura? domanda, sono curioso: perché così tante librerie sono così carenti nella documentazione per l'utente finale?

La mia opinione è questa:

1. Quasi tutti concordano sul fatto che leggere il codice sorgente sia più difficile che scrivere il codice sorgente.
2. Senza documentazione, è necessario leggere il codice sorgente della libreria per poter utilizzare quella libreria.
3. Pertanto, l'utilizzo della libreria non documentata è più un lavoro che ricreare la libreria da zero.
4. Di conseguenza, se vuoi che le persone utilizzino la tua libreria, ti conviene accertarti che sia documentato.

So che molti sviluppatori non amano scrivere documenti, e concorderò che può essere un lavoro noioso. Ma è un lavoro essenziale. Direi anche che è più importante che una biblioteca abbia una buona documentazione che l'interfaccia del miglior programmatore al mondo. (Le persone usano continuamente librerie di merda; pochi usano librerie non documentate)

Oh, nota che quando dico documentazione intendo vera documentazione. Caldaia non Sandcastle / Javadoc / Doxygen.

Penso che tu abbia principalmente risposto alla tua domanda: perché nella maggior parte dei casi, gli sviluppatori non si preoccupano. Il problema è particolarmente diffuso nei progetti di volontariato.

Penso che ci sia un altro grosso problema: in molti casi, gli sviluppatori non hanno davvero sviluppato un modello generale di come funziona la loro biblioteca (o hanno solo difficoltà a articolare chiaramente quel modello). Sfortunatamente, articolare quel modello e come i pezzi del software si incastrano è spesso la parte più importante della documentazione.

In un caso tipico, ciò che è scritto ha una molto panoramica di alto livello ( "Questa è una libreria per fare cose interessanti!") E poi una descrizione molto a basso livello (tipo e la descrizione di ogni parametro da passare a ogni funzione). Sfortunatamente, raramente esiste un livello intermedio sulla teoria generale di come le cose dovrebbero funzionare, come i pezzi si incastrano, ecc. Gran parte di ciò risale al fatto che spesso gli sviluppatori non hanno tentato di formare, razionalizzare o capire il loro codice a quel particolare livello di dettaglio. Almeno in alcuni casi che ho visto, gli sviluppatori a cui è stato chiesto di scrivere la documentazione a quel livello lo hanno trovato abbastanza problematico - al punto che molti volevano riscrivere il codice in modo che fosse più organizzato e più facile da spiegare a quel livello di dettaglio.

Scrivere bene a quel livello di astrazione è spesso difficile - e se lo sviluppatore non ci ha davvero pensato a quel livello di astrazione, troveranno spesso il codice un po 'imbarazzante e potrebbero voler riscriverlo prima di essere felici di rilasciarlo affatto.

Penso che a volte sia perché lo sviluppatore è così coinvolto nel codice che è "ovvio" per lui / lei come funziona e non riescono a capire perché non sia ovvio per nessun altro. Allo stesso modo, un sacco di siti Web di prodotti dicono quanto sia meraviglioso il loro prodotto, ma in realtà non ti dicono cosa fa!

Hai sottolineato tu stesso la risposta:

So che molti sviluppatori non amano scrivere documenti, e concorderò che può essere un lavoro noioso.

Come programmatori, ci piace scrivere codice, ma pochissimi di noi amano scrivere documenti.

Mentre ogni buon programmatore conosce il valore di una buona documentazione, ci vuole anche un bel po 'di tempo per farlo correttamente. Dato che non è divertente e richiede molto tempo, viene messo nella pila "da fare dopo" in modo che non venga mai raggiunto a un livello soddisfacente.

Come nota a margine, è anche molto difficile per un programmatore scrivere la documentazione sul proprio prodotto. Poiché conoscono così bene il sistema, alcune cose sono ovvie per loro. Queste parti spesso non vengono mai menzionate nonostante non siano evidenti per il consumatore.

Scrivere documentazione è un'abilità. Come tutte le abilità ci vuole pratica. Il tempo e l'impegno che dedichiamo alla scrittura del codice hanno un immediato rimborso. Possiamo vedere la nuova funzionalità, il bug risolto, la velocità migliorata. La scrittura della documentazione ha un payoff ritardato. Aiuta a lungo termine poiché nuove persone hanno bisogno di lavorare sul codice o se torniamo a lavorare sul codice mesi o anni dopo. È naturale che ci concentriamo sul breve termine.

A mio avviso, la capacità di scrivere una buona documentazione è uno dei tratti chiave che distingue i grandi programmatori dai programmatori mediocri.

La persona più qualificata per scrivere la documentazione è anche la persona che ha la minima motivazione per farlo:

lui (o lei) è:

• principalmente un manutentore della libreria, piuttosto che un utente. Quindi più piccola e semplice è la libreria, più facile è il suo lavoro. Mantenere mezzo romanzo in aggiunta al codice rende solo più difficile il suo lavoro,
• conosce a fondo la biblioteca, quindi non ha bisogno della documentazione,
• è un programmatore, vuole scrivere codice, non documentazione.

Non riesco a pensare a nessuno che abbia meno probabilità di andare "Hmm, dovrei davvero passare qualche ora a scrivere della documentazione adeguata per questo". Perché dovrebbe?

E, naturalmente, probabilmente non aiuta che ci sia questa leggenda urbana in giro che i commenti autogenerati in stile doxygen sono tutto ciò che serve in termini di documentazione.

Quindi, anche nei rari casi in cui uno sviluppatore è effettivamente disposto a scrivere documentazione, è una probabilità 50/50 che lo sviluppatore sia stato sottoposto al lavaggio del cervello da questo culto nel pensare che tutto ciò che serve è compilare alcuni di questi commenti, dicendoti gemme come che "la funzione Foo getFoo()restituisce un oggetto di tipo Foo e viene utilizzata per ottenere l'oggetto Foo".

Documentazione? Non abbiamo bisogno di documentazione puzzolente!

So come funziona il codice, quindi perché dovrei perdere tempo a documentare il mio codice? Oltre a questo, devo fare questo progetto entro venerdì e non riuscirò quasi a farlo così com'è ...