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

14

En una línea similar a la ¿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 faltan en la documentación del usuario final?

Mi punto de vista es este:

  1. La mayoría de las personas están de acuerdo en que leer el código fuente es más difícil que escribir el código fuente.
  2. Sin documentación, uno debe leer el código fuente de la biblioteca para poder 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 las personas usen su biblioteca, sería 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 buena documentación que la mejor interfaz de programador del mundo. (La gente usa bibliotecas de mierda todo el tiempo; pocas usan bibliotecas no documentadas)

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

    
pregunta Billy ONeal 16.08.2011 - 10:02

6 respuestas

20

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

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 con claridad). Desafortunadamente, articular ese modelo y cómo encajan las piezas del software suele ser la parte más importante de la documentación.

En un caso típico, lo que está escrito tiene una descripción general de alto nivel muy ("¡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 a 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. Mucho de esto se remonta al hecho de que los desarrolladores a menudo no han intentado formar, racionalizar o comprender su Código a ese nivel particular de detalle. Al menos en algunos casos, a los desarrolladores a los que se les pidió que escribieran la documentación a ese nivel les pareció bastante problemático, hasta el punto de que muchos querían volver a escribir el código para que fuera más organizado y más fácil de explicar a ese nivel de detalle.

Escribir bien en ese nivel de abstracción es a menudo difícil, y si el desarrollador no lo ha pensado al respecto en ese nivel de abstracción, a menudo encontrarán el código algo embarazoso, y puede querer reescribirlo antes de que estén contentos de haberlo liberado.

    
respondido por el Jerry Coffin 16.08.2011 - 10:23
9

A veces creo que 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. De manera similar, muchos sitios web de productos dicen lo maravilloso que es su producto, ¡pero en realidad no le dicen lo que hace!     

respondido por el Pete Cordell 16.08.2011 - 11:36
5

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 sabe el valor de una buena documentación, también toma bastante tiempo hacerlo correctamente. Como no es agradable y lleva mucho tiempo, se coloca en la pila de "tareas pendientes" para que nunca se haga a un nivel satisfactorio.

Como nota al margen, también es muy difícil para un programador escribir documentación sobre 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.

    
respondido por el Tom Squires 16.08.2011 - 10:12
3

Escribir documentación es una habilidad. Como todas las habilidades se necesita práctica. El tiempo y el esfuerzo que dedicamos a escribir el código tienen una recompensa inmediata. Podemos ver la nueva característica, el error corregido, la velocidad mejorada. Escribir documentación tiene un pago demorado. A la larga, es útil que personas nuevas necesiten trabajar en el código o si volvemos a trabajar en el código meses o años después. Es natural que nos centramos 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.

    
respondido por el Jim C 16.08.2011 - 14:37
3

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

él (o ella) es:

  • principalmente un mantenedor de la biblioteca, en lugar de un usuario. Así que cuanto más pequeña y simple sea la biblioteca, más fácil será su trabajo. Mantener la mitad de una novela además de al código solo dificulta su trabajo,
  • conoce la biblioteca de adentro hacia afuera, por lo que no necesita la documentación,
  • es un programador, quiere escribir código, no documentación.

No puedo pensar en alguien que tenga menos probabilidades de ir "Hmm, realmente debería dedicar unas horas a escribir la documentación adecuada para esto". ¿Por qué lo haría?

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

Por lo tanto, incluso en los casos raros en que un desarrollador está realmente dispuesto a escribir documentación, existe una posibilidad del 50/50 de que este culto haya hecho un lavado de cerebro al desarrollador para pensar que todo lo que se necesita se está llenando algunos de esos comentarios, que le dicen gemas como que "la función Foo getFoo() devuelve un objeto de tipo Foo, y se usa para obtener el objeto Foo".

    
respondido por el jalf 16.08.2011 - 23:19
1
  

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

Sé cómo funciona el código, ¿por qué me dedico tiempo a documentar mi código? Además de eso, tengo que hacer este proyecto para el viernes y apenas voy a hacerlo como está ...

    
respondido por el IAbstract 16.08.2011 - 23:38

Lea otras preguntas en las etiquetas