¿Por qué tantas bibliotecas no tienen / tienen poca documentación? [cerrado]

En una línea similar a la de ¿Cómo pueden tener éxito los proyectos de código abierto sin documentación sobre su diseño o arquitectura? pregunta, tengo curiosidad: ¿por qué hay tantas bibliotecas que carecen de documentación para el usuario final?

Mi punto de vista es este:

1. La mayoría está de acuerdo en que leer el código fuente es más difícil que escribirlo.
2. Sin documentación, uno debe leer el código fuente de la biblioteca para usar esa biblioteca.
3. Por lo tanto, usar la biblioteca no documentada es más trabajo que simplemente recrear la biblioteca desde cero.
4. Como resultado, si desea que la gente use su biblioteca, es mejor que se asegure de que esté documentada.

Sé que a muchos desarrolladores no les gusta escribir documentos, y estoy de acuerdo en que puede ser un trabajo tedioso. Pero es un trabajo esencial. Incluso diría que es más importante que una biblioteca tenga una buena documentación que la mejor interfaz de programador del mundo. (La gente usa bibliotecas de mierda todo el tiempo; pocos usan bibliotecas indocumentadas)

Ah, tenga en cuenta que cuando digo documentación, me refiero a documentación real. No Sandcastle / Javadoc / Doxygen repetitivo.

Creo que ha respondido principalmente a su propia pregunta: porque en la mayoría de los casos, los desarrolladores simplemente no se molestarán. El problema es especialmente frecuente en proyectos de voluntariado.

Sin embargo, creo que hay otro problema importante: en muchos casos, los desarrolladores realmente no han desarrollado un modelo general de cómo funciona su biblioteca (o simplemente tienen dificultades para articular ese modelo claramente). Desafortunadamente, articular ese modelo y cómo encajan las piezas del software es a menudo la parte más importante de la documentación.

En un caso típico, lo que está escrito tiene una visión general de muy alto nivel ("¡Esta es una biblioteca para hacer cosas geniales!") Y luego una descripción de muy bajo nivel (tipo y descripción de cada parámetro que se pasará a cada función). Desafortunadamente, rara vez hay un nivel intermedio sobre la teoría general de cómo se supone que funcionan las cosas, cómo encajan las piezas, etc. Gran parte de esto se remonta al hecho de que los desarrolladores a menudo no han intentado formar, racionalizar o comprender su código en ese nivel particular de detalle. Al menos en algunos casos que he visto, los desarrolladores a los que se les pidió que escribieran documentación a ese nivel lo encontraron bastante problemático, hasta el punto de que muchos querían reescribir el código para que fuera más organizado y más fácil de explicar a ese nivel. detalle.

Escribir bien en ese nivel de abstracción a menudo es difícil, y si el desarrollador realmente no lo ha pensado en ese nivel de abstracción, a menudo encontrarán el código algo vergonzoso y tal vez quieran reescribirlo antes de estar contentos. sobre liberarlo en absoluto.

Creo que a veces es porque el desarrollador está tan envuelto en el código que es "obvio" para él / ella cómo funciona y no pueden ver por qué no sería obvio para nadie más. Del mismo modo, muchos sitios web de productos dicen lo maravilloso que es su producto, ¡pero en realidad no le dicen lo que hace!

Usted mismo señaló la respuesta:

Sé que a muchos desarrolladores no les gusta escribir documentos, y estoy de acuerdo en que puede ser un trabajo tedioso.

Como programadores, disfrutamos escribiendo código, pero muy pocos de nosotros también disfrutamos escribiendo documentación.

Si bien cualquier buen programador conoce el valor de una buena documentación, también lleva bastante tiempo hacerlo correctamente. Como no es agradable y lleva mucho tiempo, se coloca en la pila "para hacer más tarde", por lo que nunca se hace a un nivel satisfactorio.

Como nota al margen, también es muy difícil para un programador escribir documentación en su propio producto. Como conocen tan bien el sistema, ciertas cosas son obvias para ellos. Estas partes a menudo nunca se mencionan a pesar de no ser obvias para el consumidor.

Escribir documentación es una habilidad. Como todas las habilidades, se necesita práctica. El tiempo y el esfuerzo que pasamos escribiendo código tiene una recompensa inmediata. Podemos ver la nueva característica, el error corregido, la velocidad mejorada. Escribir documentación tiene un pago retrasado. Ayuda a largo plazo ya que las nuevas personas necesitan trabajar en el código o si volvemos a trabajar en el código meses o años después. Es natural que nos centremos en el corto plazo.

En mi opinión, la capacidad de escribir buena documentación es uno de los rasgos clave que distingue a los grandes programadores de los programadores mediocres.

La persona que está mejor calificada para escribir documentación también es la persona que tiene la menor motivación para hacerlo:

él (o ella) es:

• principalmente un mantenedor de la biblioteca, en lugar de un usuario. Entonces, cuanto más pequeña y simple es la biblioteca, más fácil es su trabajo. Mantener media novela además del código solo dificulta su trabajo,
• conoce la biblioteca al revés, por lo que no necesita la documentación,
• es programador, quiere escribir código, no documentación.

No puedo pensar en nadie que sea menos propenso a decir "Hmm, realmente debería pasar unas horas escribiendo la documentación adecuada para esto". ¿Por qué lo haría él?

Y, por supuesto, probablemente no ayude que exista esta leyenda urbana que dice que los comentarios autogenerados de estilo doxygen son todo lo que necesita en términos de documentación.

Entonces, incluso en los raros casos en que un desarrollador está realmente dispuesto a escribir documentación, es una probabilidad del 50/50 de que el culto haya sido lavado por el cerebro para pensar que todo lo que se necesita es completar algunos de esos comentarios, diciéndole gemas como que "la función Foo getFoo()devuelve un objeto de tipo Foo, y se usa para obtener el objeto Foo".

¿Documentación? ¡No necesitamos documentación apestosa!

Sé cómo funciona el código, entonces, ¿por qué pasaría tiempo documentando mi código? Además de eso, tengo que tener este proyecto terminado para el viernes y apenas voy a lograrlo tal como está ...