¿Qué pasa con la aversión a la documentación en la industria?

Parece haber una aversión a escribir incluso la documentación más básica. Nuestro proyecto READMEs es relativamente simple. Ni siquiera hay listas actualizadas de dependencias en los documentos.

¿Hay algo que desconozco en la industria que haga que a los programadores no les guste escribir documentación? Puedo escribir párrafos de documentos si es necesario, entonces, ¿por qué otros son tan reacios?

Más importante aún, ¿cómo los convenzo de que escribir documentos nos ahorrará tiempo y frustración en el futuro?

No creo que sea útil especular sobre las motivaciones de las personas que no están adoptando algo que crees que es una buena práctica o que continúan haciendo algo que ves como una mala práctica. En este negocio, las personas que caen en una o ambas categorías superarán con creces a las que verás cara a cara, así que deja de volverte loco.

En cambio, concéntrese en el problema y las posibles soluciones.

1. Escriba buena documentación usted mismo

Es posible que no sea realista esperar que todos en su equipo dirijan sus esfuerzos a las cosas que ve como un problema. Esto es especialmente cierto si eres relativamente nuevo en el equipo. Me aventuraría a adivinar que sí, porque si fueras miembro fundador del equipo, parece muy probable que ya hayas resuelto este problema desde el principio.

Considere, en cambio, trabajar hacia el objetivo de escribir buena documentación usted mismo y lograr que la gente la use. Por ejemplo, si alguien de mi equipo me pregunta dónde está el código fuente del Proyecto A o qué configuración especial necesita el Proyecto A, lo dirijo a la página wiki del Proyecto A.

Si alguien me pregunta cómo escribir una nueva implementación de Factory F para personalizar una cosa para el Cliente C, les digo que está en la página 10 de la guía del desarrollador.

La mayoría de los desarrolladores odian hacer preguntas que puedan hacer que parezcan que no pueden simplemente "leer el código" incluso más de lo que odian leer la documentación, por lo que después de suficientes respuestas de esta naturaleza, primero irán a los documentos.

2. Demuestre el valor de su documentación

Asegúrese de aprovechar todas las oportunidades para señalar dónde está demostrando su valor la documentación (o lo habría hecho, si se usara). Intenta ser sutil y evita "te lo dije", pero es perfectamente legítimo decir cosas como

Para referencia futura, la página wiki de este proyecto tiene información sobre la rama del código central que se creó para el soporte continuo de la versión 2.1, por lo que en el futuro podemos evitar tener que hacer una prueba de regresión completa si las personas que mantienen versiones publicadas verifican la wiki antes de revisar el código.

o

Estoy tan contento de haber anotado los pasos para hacer la Tarea T. Realmente no me importa si nadie más la usa, ya me ahorró más tiempo del que pasé escribiendo.

3. Conseguir la gestión a bordo

Después de unos pocos incidentes en los que tener documentación está probadamente ahorrando tiempo / dinero, probablemente notará un "deshielo" distinto hacia la documentación. Este es el momento de presionar el punto al comenzar a incluir el tiempo de documentación en sus estimaciones (aunque honestamente, generalmente actualizo / creo documentos mientras se ejecutan procesos largos, como compilaciones o registros). Especialmente si se trata de una contratación reciente, es posible que esto no se cuestione, sino que se vea como una nueva práctica que está trayendo de un lugar de trabajo anterior (que bien podría ser).

Palabra de advertencia: a la mayoría de los jefes no les gusta hacer que la gente haga nada, especialmente cosas que no están directamente vinculadas a una tarea facturable, así que no esperes que este apoyo sea en forma de un mandato. En cambio, es más probable que te dé rienda suelta para escribir más documentos.

4. Fomente la documentación cuando la vea

Tal vez parte de la razón por la cual las personas no escriben documentos tan a menudo como deberían es porque sienten que nadie lo está leyendo. Entonces, cuando vea algo que le guste, asegúrese de mencionar al menos que estaba contento de que estuviera disponible.

Si su equipo hace revisiones de código, este es un momento en el que puede escribir una o dos palabras sutiles para alentar los buenos comentarios.

Gracias por documentar la solución para el error B en el Marco G. No sabía sobre eso, y no creo que podría haber entendido lo que estaba haciendo sin eso allí.

Si tiene a alguien en el equipo que está realmente entusiasmado con la documentación, no está de más cultivar a esa persona yendo a almorzar o tomar un café y asegurándose de ofrecer una pequeña validación para contrarrestar el desánimo que pueden obtener al ver al resto del equipo. no valora tanto la documentación.

Más allá de eso, realmente no es su problema a menos que esté en una posición de liderazgo o gerencia. Puedes llevar un caballo al agua, pero no puedes obligarlo a beber. Si no es su caballo, es posible que no esté contento de que tenga sed, pero todo lo que puede hacer es llenar el comedero.

Hay dos factores principales en mi experiencia:

Plazos

La mayoría de las empresas están tan limitadas por la fecha que el control de calidad, la deuda tecnológica y el diseño real se reducen solo para que el gerente del proyecto no se vea mal o cumpla con un plazo de cliente absurdo y demasiado prometido. En este entorno donde incluso se reduce la calidad funcional, una inversión a largo plazo como la documentación tiene pocas posibilidades.

Cambio

Una práctica recomendada relativamente nueva para los desarrolladores es quitar el énfasis a los comentarios. La idea es que mantener la información en dos lugares (el código [incluidas las pruebas] y los comentarios sobre el código) conlleva una gran sobrecarga para mantenerlos sincronizados por poco beneficio. "Si su código es tan difícil de leer que necesita comentarios, ¿no pasaría más tiempo limpiando el código?"

Yo personalmente ni siquiera miraré más comentarios. El código no puede mentir.

La documentación sigue la misma veta. Con la adopción generalizada de ágil, las personas reconocen que los requisitos cambian regularmente. Con el uso generalizado de la refactorización, la organización del código cambiará considerablemente. ¿Por qué pasar el tiempo documentando todo esto que está destinado a cambiar? El código y las pruebas deberían hacer un buen trabajo al hacerlo.

Aquí hay varios factores en juego:

1. El código bien escrito es su propia documentación. En igualdad de condiciones, es mejor escribir un código más claro que hable por sí mismo, en lugar de más documentación. Haga eso, y necesitará modificar menos documentación cuando cambie ese código.

2. Escribir documentación es posiblemente una habilidad diferente que escribir código. Algunos desarrolladores de software son mejores que otros. Algunos son mucho mejores escribiendo código que escribiendo documentación.

3. La documentación solo debe escribirse una vez , no dos veces (una vez en el código fuente y nuevamente en la guía del programador). Es por eso que tenemos cosas como comentarios XML y generadores de documentación. Desafortunadamente, el uso de tales herramientas puede ser más complicado y engorroso que simplemente escribir la documentación a mano, por lo que no se ven esas herramientas ampliamente utilizadas.

4. La buena documentación lleva mucho tiempo y es difícil hacerlo bien. En igualdad de condiciones, puede ser más valioso escribir código nuevo que escribir documentación para código ya existente.

5. Cuando el código cambia, también debe cambiar la documentación. Cuanta menos documentación haya, menos se debe cambiar.

6. Nadie lee la documentación de todos modos, entonces, ¿por qué molestarse?

Elefante en la sala: los programadores no son (necesariamente) escritores. Tampoco son necesariamente susceptibles de desarrollar sus implementaciones a escritores técnicos. Segundo elefante en la sala: los escritores técnicos generalmente no pueden desarrollar detalles útiles para futuros desarrolladores (incluso si los desarrolladores se dignasen a explicárselos).

Un sistema complejo puede volverse casi inescrutable con el tiempo sin la documentación adecuada. El código se vuelve menos valioso inversamente proporcionalmente a su capacidad de desplazamiento [sic]. Resuelto, la gerencia contrata a un ingeniero de software que puede leer el código y los detalles de los desarrolladores, le paga a una tarifa de desarrollador y le ordena documentar y mantener la documentación. Este escritor puede leer el código y sabrá qué preguntas hacer y completará los detalles según sea necesario. Al igual que tiene un departamento de control de calidad, tiene un departamento de documentación interno.

El código se volverá más valioso, ya que puede licenciarlo a un tercero (porque él puede entenderlo), el código se puede auditar y mejorar / refactorizar más fácilmente, tendrá una mejor reutilización del código incluso donde pueda fácilmente descubra las versiones más livianas de su software, y podrá introducir nuevos desarrolladores más fácilmente en el proyecto, a sus ingenieros de soporte les encantará trabajar para usted.

Esto nunca va a suceder.

Más importante aún, ¿cómo los convenzo de que escribir documentos nos ahorrará tiempo y frustración en el futuro?

¿Hace eso?

Hay dos tipos de documentación:

Documentación útil

Documenta cómo usar un producto terminado, una API, qué direcciones IP o nombres de URL tienen nuestros servidores, etc. Básicamente, todo lo que se usa de manera intensiva y a diario. La información incorrecta se descubrirá rápidamente y se corregirá. Necesita ser fácil y fácil de editar (por ejemplo, Wiki en línea).

Documentación inútil

Documentación que cambia a menudo, muy pocas personas están interesadas en ella y nadie sabe dónde encontrarla. Como el estado actual de una característica que se está implementando. O documentos de requisitos en un documento de Word oculto en algún lugar de SVN, actualizado hace 3 años. Esta documentación tomará tiempo para escribir, y tiempo para descubrir que está mal más tarde. No puede confiar en este tipo de documentación. Es inútil. Pierde el tiempo.

A los programadores no les gusta escribir o leer documentación inútil. Pero si puede mostrarles la documentación que es útil, la escribirán. Tuvimos un gran éxito con él en mi último proyecto cuando introduje un Wiki donde pudimos escribir toda la información que necesitamos a menudo.

Diría que la razón principal es la falta de voluntad y la falta de comprensión de la función de la documentación. Hay una serie de clases de documentación a considerar:

Documentación de producto / lanzamiento

Esto es todo lo que sale con su producto 'terminado'. Esto es más que solo manuales, esto es README, registros de cambios, instrucciones y demás. En teoría, puede salirse con la suya al no escribir estos, pero termina con un producto que la gente no quiere usar, o una carga de soporte que es innecesariamente costosa.

Documentación API

Esto describe algo que debería ser relativamente estático. Dado que numerosos consumidores pueden estar codificando su API, debe ser lo suficientemente estable como para que alguna prosa que describa cómo usarla tenga valor. Describir qué parámetros son compatibles, cuál puede ser el valor de retorno y qué errores pueden generarse permitirá a otros usuarios la capacidad de comprender su API en el nivel correcto de abstracción: la interfaz ( no la implementación).

Comentarios de código

La opinión de la industria sobre los comentarios parece estar cambiando, por el momento. Cuando comencé a codificar profesionalmente, los comentarios eran una condición sine qua non cuando se trataba de escribir código. Ahora, la moda es escribir código que sea tan claro que los comentarios sean innecesarios. Me arriesgaría a adivinar que esto se debe, en parte, al hecho de que muchos lenguajes modernos están escritos en un nivel mucho más alto y es mucho más fácil escribir código legible en Java, JavaScript, Ruby, etc. de lo que estaba en ensamblador , C, FORTRAN, etc. Por lo tanto, los comentarios tenían un valor mucho mayor.

Todavía creo que hay valor en los comentarios que describen la intención de una sección de código, o algunos detalles sobre por qué se eligió un cierto algoritmo en lugar de uno más obvio (para evitar que los demonios de refactorización excesivamente entusiastas 'arreglen' el código que no t realmente necesita ser reparado).

Desafortunadamente, hay mucho egoísmo, racionalización y autoengaño involucrados en las decisiones de los programadores de no documentar. La realidad es que, como el código, la audiencia principal para la documentación son otras personas. Por lo tanto, las decisiones de escribir (o no escribir) documentación, en cualquier nivel, deben tomarse a nivel de equipo. Para los niveles más altos de abstracción, puede tener más sentido tener a alguien que no sea desarrollador para hacerlo. En cuanto a la documentación a nivel de comentarios, se debe llegar a un acuerdo sobre el propósito y la intención de los comentarios, especialmente en equipos mixtos de habilidades y experiencia. No es bueno tener desarrolladores senior escribiendo código que los desarrolladores junior no pueden abordar. Alguna documentación bien ubicada y bien escrita puede permitir que un equipo opere de manera mucho más efectiva

Aquí están mis dos centavos.

1. El Manifiesto Ágil dice "Software de trabajo sobre documentación exhaustiva" y no todos leen para llegar a "Es decir, si bien hay valor en los elementos de la derecha, valoramos más los elementos de la izquierda".

2. Lamentablemente, es común en https://en.wikipedia.org/wiki/Code_and_fix y la documentación no funciona con este modelo (se desincroniza).

3. La industria del desarrollo de software no está bien regulada. No existe un requisito legal para escribir documentación.

4. El código autodocumentado es la tendencia actual.

Dicho esto, creo que hay mucha buena documentación por ahí.

La documentación lleva tiempo, y sospecho que muchos desarrolladores han tenido demasiados encuentros con documentación que era peor que inútil. Se les ocurre la idea de que la documentación no solo les causará problemas a su gerente (el mismo tipo que sigue cortando la parte de control de calidad del horario), sino que no ayudará a nadie, incluidos ellos.

Cualquier documentación medio decente es una inversión en el futuro. Si no le importa el futuro (porque no piensa más allá del próximo cheque de pago o porque cree que no será su problema), entonces la idea de hacer la documentación es extremadamente dolorosa.

Muchas de las otras respuestas pasan por alto al punto de que hay al menos dos tipos de documentación: un conjunto para otros desarrolladores y un conjunto diferente para los usuarios finales. Dependiendo de su entorno, también puede necesitar documentación adicional para los administradores del sistema, los instaladores y el personal de la mesa de ayuda. Cada público objetivo tiene diferentes necesidades y niveles de comprensión.

Considere el desarrollador (estéreo) típico: es un codificador por elección. Ha elegido una carrera fuera del ojo público y pasa largas horas detrás de un teclado comunicándose principalmente consigo mismo. El proceso de documentación es una forma de comunicación y el conjunto de habilidades requeridas para producir una buena documentación es antitético a las habilidades requeridas para producir un buen código.

Un buen escritor de documentación puede comunicarse en varios idiomas: el idioma de los usuarios, el idioma de administración, el idioma del personal de soporte, el idioma de los desarrolladores. Es el trabajo de un escritor de documentación comprender lo que comunica un codificador y traducirlo a una forma que todos los otros grupos puedan entender.

Cuando esperas que los codificadores desarrollen la habilidad necesaria para convertirse en buenos comunicadores (escritos o de otro tipo), la cantidad de tiempo dedicado a perfeccionar el conjunto de habilidades primario (¡codificación!) Disminuye. Cuanto más se aleje de su zona de confort (codificando y comunicándose con otros codificadores), se necesitará más tiempo y energía para realizar bien la tarea. Puede esperar razonablemente que un programador profesional desee centrarse principalmente en sus competencias básicas, a expensas de todos los demás.

Por este motivo, es mejor dejar la documentación (con la excepción de los comentarios de código en línea) a los comunicadores, no a los codificadores.

Leer el código te muestra cómo funciona. No puede explicar por qué : necesita comentarios.

Leer el código le muestra el nombre de un método y los tipos de los parámetros. No puede explicar la semántica, o la intención exacta del autor: necesita comentarios.

Los comentarios no reemplazan la lectura del código, sino que le agregan.

La documentación no se ejecuta como el código. Como resultado, a menudo no hay bucles de retroalimentación efectivos para verificar que la documentación esté en su lugar y esté completa. Esta es la misma razón por la que los comentarios de código tienden a pudrirse.

Donald Knuth promovió la programación literaria como una forma de mejorar la calidad del software, escribiendo efectivamente la documentación con el código. He visto algunos proyectos que han utilizado este enfoque con bastante eficacia.

Personalmente, trato de mantener la tendencia moderna de mantener la API pública de su código lo más legible posible y usar pruebas unitarias para documentar el uso para otros desarrolladores. Creo que esto es parte de la idea más importante de que su API sea de una forma que pueda ser explorada y descubierta. Creo que este enfoque es parte de lo que HATEOAS intenta lograr con los servicios web.

Un punto menor, pero que parece ser importante con algunos desarrolladores que escriben poca documentación desagradable: no pueden escribir. Si tiene una aproximación del sistema de 10 dedos, tiende a escribir más documentación solo porque es fácil. Pero si estás atrapado con la caza y el picoteo, estás perdido. Si fuera responsable de contratar, esto es realmente algo que comprobaría.

A las personas que no les gusta leer documentación no les gusta escribir documentación. Muchos programadores harán todo lo posible para evitar leer un documento a fondo.

No se concentre en la escritura, concéntrese en la lectura. Cuando los programadores lean la documentación y asimilen cosas de ella, verán el valor y estarán mucho más inclinados a escribir algo.

Cuando comencé mi trabajo actual y asumí un proyecto de hardware + software de las personas que anteriormente habían estado trabajando en él, me dieron un documento de más de cien páginas que describía el sistema. Debe haber tomado días para producir. Lo miré tal vez dos veces. A pesar de la gran cantidad de información allí, rara vez respondía las preguntas reales que tenía sobre el sistema, e incluso cuando lo hizo, fue más rápido mirar el código.

Después de suficientes experiencias como esa, empiezas a pensar, ¿por qué molestarte? ¿Por qué dedicar su tiempo a responder preguntas que la gente nunca hizo? Empiezas a darte cuenta de lo verdaderamente difícil que es predecir qué información buscarán las personas en la documentación; inevitablemente está lleno de hechos que resultan inútiles, poco claros u obvios, y que carecen de las respuestas a las preguntas más apremiantes. Recuerde, producir documentación útil es un esfuerzo para predecir el comportamiento humano. Así como es poco probable que el diseño de una interfaz de usuario tenga éxito antes de que haya pasado por múltiples iteraciones de pruebas y depuración, es ingenuo pensar que es posible escribir documentación útil basada solo en las expectativas de cómo las personas interpretarán el sistema y qué papel que desempeñará la documentación y su lenguaje en esa interpretación.

Tiendo a pensar que la mayor parte de la presión para escribir documentación se debe al hecho de que es una tarea desagradable y a la gente le gusta culparse mutuamente por hacer tareas desagradables ("¡No te has comido tu filboid studge!").

SIN EMBARGO

No creo que la documentación sea, en todos los sentidos, inútil. Creo que es inútil principalmente cuando las personas ven la documentación como esta carga adicional que debe cumplirse antes de que se termine un trabajo, como un último trabajo de limpieza que debe apresurarse y como una casilla para verificar. La documentación es algo que debe trabajar en los aspectos de su día que siempre hace de todos modos. Creo que el correo electrónico es una forma particularmente buena de hacer documentación. Cuando agregue una nueva función, escriba a algunas personas un correo electrónico rápido diciendo qué es. Cuando dibuje un nuevo esquema, genere un PDF y envíelo a cualquier persona que pueda estar interesada. Las ventajas del correo electrónico son:

1. La gente generalmente revisa el correo electrónico, mientras que nadie navega por una carpeta llamada "doc".

2. El correo electrónico existe en contexto, rodeado de otros correos electrónicos que discuten la característica y las características relacionadas y todo lo que estaba sucediendo en ese momento.

3. El correo electrónico es corto y enfocado y tiene una línea de asunto.

4. El correo electrónico permite a las personas que se preocupan hacer preguntas de inmediato,

5. El correo electrónico es altamente buscable, porque la gente lo usa para todo y los clientes de correo han avanzado bastante con los años.

6. Si está en un correo electrónico, al menos otra persona sabe dónde encontrarlo.

En teoría, debería parecer que los comentarios en código también deberían ser "aspectos de tu día que siempre haces de todos modos", pero para ser sincero, nunca leo comentarios en código. No estoy seguro de por qué, pero simplemente no son muy útiles, tal vez porque hay una falta de contexto, que el correo electrónico resuelve.