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

No creo que sea útil especular sobre las motivaciones de las personas que no están adoptando algo que usted considera una buena práctica o que continúan haciendo algo que consideran una mala práctica. En este negocio, las personas que caen en una o ambas de esas categorías lejos superarán en número a las personas a las que verás cara a cara, así que deja de volverte loco.

En su lugar, enfócate en el problema y las posibles soluciones.

1. Escribe buena documentación tú mismo

Puede que no sea realista esperar que todos los miembros de su equipo dirijan sus esfuerzos a las cosas que ven como un problema. Esto es especialmente cierto si eres un recién llegado al equipo. Me atrevería a adivinar que lo eres, porque si fueras un 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 una buena documentación y hacer que la gente la use. Por ejemplo, si alguien en mi equipo me pregunta dónde está el código fuente del Proyecto A o qué configuración especial necesita el Proyecto A, les 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 algo para el Cliente C, les digo que está en la página 10 de la guía para desarrolladores.

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, acudirán primero a la documentación.

2. Demuestre el valor de su documentación

Asegúrese de aprovechar cada oportunidad para señalar dónde la documentación está demostrando su valor (o la tendría, si se usara). Trate de ser sutil y evite "Te lo dije", pero es perfectamente legítimo decir cosas como

  

Para futuras referencias, la página wiki de este proyecto contiene 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 realizar una prueba de regresión completa si las personas que mantienen Las versiones publicadas revisan el wiki antes de revisar el código.

o

  

Estoy muy contento de haber anotado los pasos para realizar la Tarea T. Realmente no me importa si nadie más lo usa, ya me ha ahorrado más tiempo del que dediqué a escribirlo.

3. Obtener la gestión a bordo

Después de algunos incidentes en los que tener documentación puede ahorrar tiempo / dinero, es probable que note un "deshielo" distintivo 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á adquiriendo desde un lugar de trabajo anterior (lo que podría ser).

Advertencia: a la mayoría de los jefes no les gusta obligar a las personas a hacer nada, especialmente las cosas que no están directamente vinculadas a una tarea facturable, así que no espere que este apoyo esté en la Forma de un mandato. En su lugar, es más probable que le dé bastante libertad para escribir más documentos.

4. Fomenta la documentación cuando la veas

Quizás parte de la razón por la que las personas no escriben documentos tan a menudo como deberían es porque sienten que nadie lo está leyendo. Entonces, cuando veas algo que te guste, asegúrate de al menos mencionar que te alegraste de que estuviera disponible.

Si su equipo realiza revisiones de código, este es un momento en el que puede colocar 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 lo sabía, y creo que no podría haber entendido lo que estaba haciendo sin eso allí.

Si tiene a alguien en el equipo que está realmente entusiasta por la documentación, no está mal cultivar a esa persona a través del almuerzo o el café y asegurarse de ofrecer una pequeña validación para contrarrestar el desaliento. pueden obtener al ver que el 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 hacer que beba. 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:

Fechas límite

La mayoría de las empresas están tan motivadas 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 para alcanzar algún plazo absurdo prometido por los clientes. En este entorno donde incluso se reduce la calidad funcional, una inversión a largo plazo como la documentación tiene pocas posibilidades.

Cambiar

Una mejor práctica relativamente nueva para los desarrolladores es no enfatizar los comentarios. La idea es que mantener la información en dos lugares (el código [incluidas las pruebas] y los comentarios en torno al código) conlleva una gran cantidad de gastos generales al mantenerlos sincronizados para obtener un pequeño beneficio. "Si su código es tan difícil de leer que necesita comentarios, ¿no sería mejor dedicar tiempo a limpiar el código?"

Yo, personalmente, ni siquiera volveré a ver los comentarios. El código no puede mentir.

La documentación sigue la misma vena. Con la adopción generalizada de Agile, las personas reconocen que los requisitos cambian regularmente. Con el uso generalizado de la refactorización, la organización del código cambiará sustancialmente. ¿Por qué dedicar tiempo a documentar todo esto que está obligado a cambiar? El código y las pruebas deberían hacer un buen trabajo al hacer eso.

Hay varios factores en juego aquí:

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 tendrá que modificar menos documentación cuando cambie ese código.

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

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

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

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

6. De todos modos, nadie lee la documentación, ¿por qué molestarse?

Elefante en la habitación: los programadores no son (necesariamente) escritores. Tampoco son necesariamente susceptibles de desarrollar sus implementaciones con escritores técnicos. Segundo elefante en la sala: los escritores técnicos generalmente no son capaces de desarrollar detalles útiles para futuros desarrolladores (incluso si los desarrolladores se dignaran 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 proporcional a su capacidad de escrutinio [sic]. Resuelto, la administración contrata a un ingeniero de software que puede leer el código y obtener detalles de los desarrolladores, le paga a un desarrollador y le obliga a 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 usted tiene un departamento de control de calidad, tiene un departamento de documentación interna.

El código se volverá más valioso, ya que puede licenciarlo a un tercero (porque él puede entenderlo), el código puede ser auditado y mejorado / re-factorizado más fácilmente, tendrá una mejor reutilización del código incluso cuando puede eliminar fácilmente versiones más ligeras 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 sucederá.

  

Más importante aún, ¿cómo los convenzo de que redactar 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 en forma pesada y de forma diaria. La información incorrecta se encontrará rápidamente y se corregirá. Debe 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 adelante. No puedes confiar en este tipo de documentación. Es inútil. Se pierde tiempo.

A los programadores no les gusta escribir o leer documentación inútil. Pero si puedes mostrarles documentación que sea útil, la escribirán. Tuvimos mucho éxito en mi último proyecto al presentar un Wiki donde podríamos escribir toda la información que necesitamos a menudo.

Yo 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:

Product / Release Documentation

Esto es todo lo que sale con su producto 'terminado'. Esto es más que solo manuales, esto es READMEs, Registros de Cambio, CÓMO-TOs y similares. En teoría, puede salirse con la suya sin escribir esto, pero termina con un producto que la gente no quiere usar, o una carga de soporte que es innecesariamente cara.

Documentación API

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

Comentarios del código

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

Todavía creo que hay valor en los comentarios que describen la intención de una sección del código, o algunos detalles sobre por qué se eligió un cierto algoritmo en lugar de uno más obvio (para evitar el exceso de celosía). refactorizando a los demonios del código de "reparación" que en realidad no necesita ser corregido).

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 que alguien, aparte de los desarrolladores, lo haga. En cuanto a la documentación a nivel de comentarios, se debe acordar un acuerdo sobre el propósito y la intención de los comentarios, especialmente en equipos de experiencia y habilidades mixtas. No es bueno que los desarrolladores senior escriban un código que los desarrolladores junior no pueden abordar. Algunos documentos bien colocados y bien escritos pueden permitir que un equipo opere de manera mucho más efectiva

Aquí están mis dos centavos.

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

2. Lamentablemente, es común a enlace y la documentación no funciona con este modelo (sale de sincronizar).

3. La industria de desarrollo de software no está bien regulada. No hay ningún requisito legal para escribir la documentación.

4. El código de auto-documentación es la tendencia actual.

Habiendo dicho eso, creo que hay mucha buena documentación por ahí.

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

Cualquier bit de 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 el hecho de que existen al menos dos tipos de documentación: una para otros desarrolladores y otra para los usuarios finales. Dependiendo de su entorno, es posible que también necesite 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 (típico) desarrollador típico: es un programador por elección. Él 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 requerido para producir una buena documentación es contrario 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. El trabajo de un escritor de documentación es entender lo que un codificador se comunica y traducirlo a un formato que todos los otros grupos puedan entender.

Cuando esperas que los programadores desarrollen la habilidad necesaria para convertirse en buenos comunicadores (escritos o no), la cantidad de tiempo dedicado a perfeccionar el conjunto de habilidades primarias (¡codificación!) disminuye. Cuanto más se aleje de su zona de confort (codificación y comunicación con otros programadores), más tiempo y energía se requerirá para realizar la tarea bien. Puede esperar razonablemente que un programador profesional desee centrarse principalmente en sus competencias básicas, a expensas de todas las demás.

Por esta razón, 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 programadores.

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

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

Los comentarios no reemplazan la lectura del código, se agregan a él.

La documentación no se ejecuta como el código. Como resultado, a menudo no hay ciclos 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ó Literate Programming como una forma de mejorar la calidad del software, escribiendo 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 gran idea de que su API sea de una forma que pueda explorarse y descubrirse. Creo que este enfoque es parte de lo que HATEOAS intenta lograr con los servicios web.

Un punto menor, pero uno que parece ser importante para algunos desarrolladores que escriben una documentación desagradablemente pequeña: no pueden escribir. Si tiene alguna aproximación del sistema de 10 dedos, tiende a escribir más documentación simplemente porque es fácil. Pero si estás atrapado con la caza y el picoteo estás perdido. Si yo fuera responsable de contratar esto, en realidad es algo que revisaría.

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

No te concentres en la escritura, enfócate en la lectura. Cuando los programadores leen la documentación y la asimilan, verán el valor y estarán más inclinados a escribir algo.

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

Después de suficientes experiencias como esa, empiezas a pensar, ¿para qué molestarse? ¿Por qué dedicar tiempo a responder preguntas que la gente nunca hizo? Empieza a darse cuenta de lo verdaderamente difícil que es predecir qué información buscará la gente 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 urgentes. Recuerde, producir documentación útil es un esfuerzo para predecir el comportamiento humano. Del mismo modo que es poco probable que el diseño de la interfaz de usuario tenga éxito antes de que haya pasado por múltiples iteraciones de prueba y depuración, es ingenuo pensar que es posible escribir documentación útil basada solo en las expectativas de cómo interpretarán el sistema las personas y qué el 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 ya la gente le gusta culparse mutuamente para realizar tareas desagradables ("¡No te has comido tu filboid studge!").

SIN EMBARGO

No creo que la documentación sea, en todo sentido, desesperada. Creo que es inútil, sobre todo cuando las personas consideran la documentación como esta carga adicional que debe cumplirse antes de que finalice un trabajo, como un último trabajo de limpieza que se debe realizar rápidamente y como una casilla que se debe marcar. 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 que diga qué es. Cuando dibuje un nuevo esquema, genere un PDF y envíelo a cualquiera que esté interesado. Las ventajas del correo electrónico son:

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

2. El correo electrónico existe en contexto, rodeado de otros correos electrónicos que analizan la función y las funciones relacionadas y cualquier otra cosa que estuviera sucediendo en ese momento.

3. El correo electrónico es corto y centrado 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 a lo largo de 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 el código también deben ser "aspectos de su día que siempre hace de todos modos", pero para ser honesto, nunca leí los comentarios en el código. No estoy seguro de por qué, pero no son muy útiles, tal vez porque hay una falta de contexto, que el correo electrónico resuelve.