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

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

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

In un caso tipico, ciò che è scritto ha una panoramica di alto livello molto ("Questa è una libreria per fare cose interessanti!") e poi una descrizione di livello molto basso (tipo e descrizione di ogni parametro da passare a ciascuna funzione). Sfortunatamente, raramente c'è un livello intermedio sulla teoria generale di come le cose dovrebbero funzionare, su come i pezzi si incastrano, ecc. Gran parte di ciò risale al fatto che gli sviluppatori spesso non hanno tentato di formare, razionalizzare o capire le loro codice a quel particolare livello di dettaglio. Almeno in alcuni casi ho visto, gli sviluppatori a cui è stato chiesto di scrivere documentazione a quel livello lo trovavano 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 dettagli.

Scrivere bene a quel livello di astrazione è spesso difficile - e se lo sviluppatore non ha davvero pensato su di esso a quel livello di astrazione, troverà spesso il codice in qualche modo imbarazzante, e potrebbe voler riscriverlo prima che siano felici di rilasciarlo affatto.

Penso che a volte sia perché lo sviluppatore è così preso dal codice che è "ovvio" per lui / lei come funziona e non riescono a capire perché non sarebbe 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 indicato tu stesso la risposta:

I know lots of developers don't like writing docs, and I'll agree it can be tedious work.

In qualità di programmatori, ci piace scrivere codice, ma molti di noi amano anche scrivere documentazione.

Mentre ogni buon codificatore conosce il valore di una buona documentazione, ci vuole anche un bel po 'di tempo per farlo correttamente. Poiché non è piacevole e richiede molto tempo, viene inserito nella pila "da fare dopo" in modo che non venga mai eseguito a un livello soddisfacente.

Come nota a margine, è anche molto difficile per un programmatore scrivere documentazione sul proprio prodotto. Poiché conoscono il sistema così bene, certe cose sono ovvie per loro. Spesso queste parti non vengono mai citate nonostante non siano ovvie per il consumatore.

Scrivere documentazione è un'abilità. Come tutte le abilità ci vuole pratica. Il tempo e gli sforzi che impieghiamo per scrivere il codice hanno un immediato riscontro. Possiamo vedere la nuova funzionalità, il bug corretto, la velocità migliorata. La documentazione scritta ha un ritardo nel pagamento. Aiuta a lungo termine come 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.

Secondo me, la capacità di scrivere una buona documentazione è uno dei tratti chiave che distingue grandi programmatori da programmatori mediocri.

La persona più qualificata per scrivere 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 biblioteca, più facile è il suo lavoro. Il mantenimento di mezzo romanzo in aggiunta al codice rende solo il suo lavoro più difficile,
• conosce la libreria al suo interno, quindi non ha bisogno della documentazione,
• è un programmatore, vuole scrivere codice, non documentazione.

Non riesco a pensare a nessuno che è meno probabile che vada "Hmm, dovrei davvero passare qualche ora a scrivere una documentazione adeguata per questo". Perché dovrebbe?

E naturalmente, probabilmente non aiuta che ci sia questa leggenda metropolitana che gira attorno ai commenti autogenerati in stile doxygen: tutto ciò che serve in termini di documentazione.

Quindi, anche nei rari casi in cui uno sviluppatore è in realtà disposto a scrivere documentazione, è una possibilità 50/50 che lo sviluppatore abbia subito il lavaggio del cervello da parte di questo culto nel pensare che tutto ciò che è necessario alcuni di questi commenti, che ti dicono gemme del genere "la funzione Foo getFoo() restituisce un oggetto di tipo Foo, ed è usato per ottenere l'oggetto Foo".

Documentation? We don't need no stinkin' documentation!

So come funziona il codice, quindi perché trascorrere del tempo a documentare il mio codice? Inoltre, devo fare in modo che questo progetto sia pronto per venerdì e riesco a malapena a renderlo così com'è ...