La documentación continua se basa en los principios de CI / CD

Las pruebas y SDLC han evolucionado a medida que la integración y la implementación continuas se han convertido en una práctica popular en las organizaciones, pero en el futuro, las organizaciones deberán aplicar los mismos principios a la documentación para mantener informados a los desarrolladores.

Esto surge del Manifiesto de Documentación Continua recientemente publicado, escrito por Omer Rosenbaum, CTO de Swimm, una compañía que ayuda a los equipos a sincronizar su código.

“Cuando un desarrollador necesita crear, interactuar o modificar el código que otra persona ha escrito, se merece documentación que le ayude a comprender la funcionalidad, el contexto, la justificación y más del código sin realizar ingeniería inversa ni perder tiempo investigando hilos y canales. para encontrar a las personas que podrían saberlo ”, escribió Rosenbaum en el libro.

CONTENIDO RELACIONADO: La documentación sigue siendo una espina en el costado de los desarrolladores

Actualmente, la documentación está escrita en sprints concentrados y cubre muchos aspectos del código a la vez, similar a cómo se implementaban las pruebas unitarias antes. A medida que el valor comercial de SDLC se mueve cada vez más rápido, los desarrolladores que escriben cierto código simplemente no tienen tiempo para usar sus herramientas actuales para producir documentación de alta calidad, según Rosenbaum.

Esto va de la mano con el hecho de que el código ahora es más complejo y los desarrolladores están cambiando entre proyectos, equipos y organizaciones con más frecuencia y necesitan una forma más rápida de entrar en un proyecto.

Aquí es donde entra en juego la documentación continua: «Para proporcionar las herramientas que permiten la integración automatizada de la documentación en los canales de desarrollo mediante la creación y actualización de la documentación de forma incremental, sincronizándola con el código base», dice Rosenbaum.

Esto se puede lograr a través de tres principios básicos descritos en el Manifiesto de documentación continua:

1. Mantente siempre actualizado – Esto se puede hacer comprobando que la documentación coincida de forma continua y automática con el estado actual del código base, y luego, de forma automática o manual, si no coincide.
2. Cree documentación cuando sea mejor: De esta manera, la documentación no se crea a posteriori y se actualiza cada vez que se corrige un error crítico o se completa una función importante.
3. Mantener vinculado al código – Cuando la documentación está vinculada a un código, hace referencia explícita y también contiene o hace referencia a las partes del código para que quede claro qué archivo fuente y qué líneas describe cada documento.

«[Code-coupled documentation] puede guiar al lector a través del viaje del código a través de diferentes archivos, clases y posiblemente múltiples repositorios. De esa manera, la documentación puede guiar al lector a través del código como si recibiera una explicación de primera mano de la persona que originalmente escribió el código. Su practicidad también podría significar que brinda al desarrollador instrucciones paso a paso para los procesos y cambios que se repiten con frecuencia ”, agregó Rosenbaum.

Al combinar el código con la documentación, las empresas también pueden medir la cobertura de la documentación, que identifica qué partes del código ya están cubiertas por la documentación y cuáles no. Finalmente, permite encontrar el código relevante mucho más rápido.