¿Por dónde empezar en documentaciones ágiles y cuáles son las mejores prácticas para empezar?

Hay un anti-patrón en muchas tiendas ágiles donde devalúan la documentación útil, probablemente debido a la creencia de que "simplemente lea el código" es una respuesta razonable.

La carga cognitiva por leer unas pocas líneas de código es significativamente mayor que la carga cognitiva por leer unos pocos párrafos de palabras; y como dice el refrán, una imagen vale más que mil palabras. Como programador, estoy seguro de que te has encontrado con situaciones en las que pasaste horas explorando una base de código solo para finalmente preguntarle a alguien que puede ilustrar el problema que estás tratando de resolver con algunos cuadros y flechas en una pizarra. .

Dicho esto, la documentación prematura , como la abstracción prematura , puede ser un antipatrón. En cambio, este es el proceso por el que paso cuando dirijo equipos de productos e ingeniería:

1. La documentación es el primer paso hacia la automatización. Si no puede escribir las palabras o hacer un dibujo de algo, será muy difícil automatizarlo.
2. Las pruebas pueden ser documentación, pero las pruebas no son documentación por defecto . it { is_expected.to return 200 }no le dice nada sobre cuál es el punto final esperado, qué se supone que debe aceptar, ni qué se supone que debe devolver.
3. La documentación es mejor cuando complementa lo invisible . En JavaScript y Ruby, por ejemplo, uso la documentación como reemplazo de los tipos de retorno de entrada y salida explícitos de Java/C#.
4. Optimice su documentación para incorporar nuevos miembros del equipo y usuarios . Es posible que no obtenga un nuevo miembro del equipo todos los días, pero la información que es más útil para las personas que recién abren la base de código/característica/módulo/biblioteca por primera vez también es la documentación más útil cuando termina regresando a ella. en unos pocos meses y no puedo recordar cuál fue la motivación para la biblioteca en primer lugar.
5. Cuando se vuelva obsoleto, ¡bórrelo! Al igual que eliminas el código muerto. ¡Es mejor tropezar debido a la falta de documentación que a una documentación engañosa!
6. En ese sentido, los diagramas desechables a veces son mejores que los editables. Los diagramas desechables a menudo son de menor fidelidad y se destilan hasta su esencia, mientras que los editables quedan obsoletos debido a la sobreespecificidad. Uno de mis colegas dibuja diagramas en papel A3 y les toma una foto. Prefiero usar mi iPad para dibujar cosas usando una aplicación de dibujo. En cada uno de estos casos, el objetivo es sacar las cosas de nuestras cabezas al mundo que se puede recrear sin un costo significativo.

¡Espero que esto ayude!

El código es su documentación más útil porque es el único documento que siempre está actualizado. Asegúrese de que su código sea fácil de leer: bien estructurado, bien nombrado y comentado cuando sea necesario.

Más allá de eso, cree los documentos que considere necesarios. No hay una regla estricta como "los diagramas de clase son imprescindibles" o "los diagramas de secuencia no valen la pena". Solo considera lo siguiente:

• El tiempo que dedicas a crear un documento no es gratis
• Su producto continuará evolucionando, eventualmente invalidando ese documento (No hay nada intrínsecamente malo en crear documentación con una vida útil limitada. SI su utilidad inmediata supera su costo total)
• El tiempo necesario para actualizar y gestionar tu documento tampoco es gratuito
• El documento sólo es útil si se lee.
  • Sin necesidad se desperdicia el esfuerzo anterior
  • Si la misma información se puede recopilar más rápido leyendo el código, el esfuerzo anterior también se desperdicia (Ejemplo clásico: API-docs que simplemente reafirman el nombre de la función)
  • Si no se puede encontrar su documentación, entonces su esfuerzo también se desperdicia (he visto demasiada documentación languidecer en algún lugar profundo de un confuso bosque de carpetas en una unidad de red no indexada donde nadie que no conozca el contenido la encontrará).

Esto no quiere decir que la documentación nunca sea útil. Cree documentación para las cosas que fueron realmente difíciles de descifrar o concretar. Revisa tus blocs de notas. Lo más probable es que ya tenga numerosas notas sobre estos temas de cuando estaba pensando en ellos por primera vez.

La única excepción en mi mente son los requisitos: siempre debe tener un documento detallado y claro que explique sus requisitos. No importa cuán turbias estén las aguas donde se encuentre ahora, siempre debe saber hacia dónde se dirige (se supone que debe estar).

• Documenta tus procesos, incluye todo lo que realmente te importa.
• Manténgalo actualizado, siempre.
• Luego, asegúrese de que la gente lo vea y lo use.