La Documentación como Código es una práctica que consiste en escribir la documentación de un proyecto de software utilizando herramientas y formatos que permiten automatizar su generación y mantenimiento.
¿Cuáles son los beneficios de la Documentación como Código?
La Documentación como Código es una práctica que ha ganado popularidad en el ámbito de la tecnología y el desarrollo de software, al ofrecer una forma eficiente y automatizada de mantener la documentación actualizada y alineada con el código fuente de un proyecto. Este enfoque implica escribir la documentación en un formato legible por máquinas, como archivos de texto estructurados o utilizando herramientas específicas, lo que permite generar y actualizar la documentación de manera automatizada a medida que se realizan cambios en el código.
Esa es el esquema más usado. Sin embargo, también hay otros, como utilizar un lenguaje de marcado dedicado para la administración de una documentación con las herramientas programáticas, ¡como si fuese un proyecto de software en si!
Atención
Es recomendable asumir que la documentación es un documento vivo. La automatización relevante para la documentación, en el código fuente u bajo otros esquemas, son una ayuda, no un substituto.
Puntos a Favor:
- Automatización de Procesos: La Documentación como Código permite automatizar la generación, revisión y despliegue de la documentación, lo que agiliza el flujo de trabajo y mejora la eficiencia operativa.
- Seguimiento de Cambios: Al estar vinculada directamente al código fuente, la documentación como código facilita el seguimiento de los cambios realizados en el proyecto, lo que ayuda a comprender el historial de desarrollo y a identificar posibles problemas.
Puntos en Contra:
- Curva de Aprendizaje: Implementar la Documentación como Código puede requerir cierto tiempo para familiarizarse con las herramientas y prácticas asociadas, lo que puede representar un desafío inicial para algunos equipos.
- Posible Complejidad: Dependiendo de la complejidad del proyecto, la gestión de la documentación como código puede resultar compleja y requerir un esfuerzo adicional en términos de planificación y mantenimiento.
¿Qué opciones de Documentación como Código ofrecemos?
La especificación Asciidoc
Asciidoc es una especificación de formato de texto simple que permite crear documentos estructurados de manera clara y legible. Con Asciidoc, los usuarios pueden escribir contenido de forma sencilla utilizando un formato de marcado ligero que se asemeja al lenguaje natural.
TIP
Este formato es ideal para la documentación técnica, manuales de usuario, informes y otros tipos de documentos.
Generación de HTML, PDF y EPUB con Asciidoctor
El toolkit Asciidoctor es una herramienta que permite convertir documentos escritos en Asciidoc a diferentes formatos de salida, como HTML, PDF y EPUB, entre otros. Asciidoctor facilita la generación de documentos con un diseño profesional y adaptable a diversas plataformas.
Generación de Páginas Web Estáticas con Antora
Por otro lado, Antora es una herramienta que se basa en Asciidoctor y permite la construcción de sitios web de documentación interactivos y de alta calidad. Antora simplifica la creación de sitios web de documentación al proporcionar funcionalidades como la organización de contenido, la generación automática de menús de navegación y la integración con fuentes de datos externas.
