La documentación es una parte esencial del ciclo de desarrollo de software. Explica cómo usar el software y puede incluir guías de usuario, referencias de API, instrucciones de instalación y notas de la versión.
La automatización de su documentación es la última tendencia, ya que puede ayudar a ahorrar tiempo, reducir errores y garantizar la coherencia. Mantener su documentación actualizada y accesible para todas las partes interesadas facilita la colaboración y la mejora continua.
Documentos como código es un enfoque de la automatización de la documentación que trata la documentación técnica como código.
¿Qué es Docs como código?
Docs as code es una filosofía de desarrollo de software que ve la documentación técnica como una forma de código. Sugiere que debe tratar la documentación con el mismo rigor y proceso que el código de software.
La idea detrás de los documentos como código es tratar la documentación como un artefacto de primera clase del proceso de desarrollo, integrándola con el ciclo de vida del software. Esto significa tratar la documentación como una parte integral del código base. Significa aplicarle los mismos procesos de control de versiones, integración continua y pruebas que aplica al propio código.
En una configuración típica de documentos como código, escribe la documentación en archivos de texto sin formato, generalmente en un lenguaje de marcado ligero como Markdown, HTML o texto reestructurado. Luego lo almacena en el mismo repositorio que el código fuente. Esto facilita la gestión y el seguimiento de los cambios tanto en el software como en la documentación. También ayuda a garantizar que la documentación esté actualizada con la última versión del código.
Por qué debería usar Docs como código
Antes de los documentos como código, la documentación a menudo se trataba como algo separado del código, creado con diferentes herramientas y procesos. Este enfoque más flexible a menudo condujo a documentación obsoleta e inconsistencias con el código. Puede aprovechar varios beneficios al adoptar el enfoque de documentos como código.
Colaboración mejorada
Documentos como código permite la colaboración entre desarrolladores, escritores técnicos y otras partes interesadas en el proceso de desarrollo. Dado que el repositorio de código alberga la documentación, es fácil que las distintas partes contribuyan y realicen cambios. Esto ayuda a garantizar que la documentación sea precisa, actualizada y completa.
Un enfoque colaborativo de la documentación ayuda a garantizar que incluya toda la información relevante y que refleje con precisión el sistema de software tal como lo interpretan todas las partes.
Automatización de Procesos y Accesibilidad
Otra ventaja de los documentos como código es que permite que las herramientas automatizadas generen y publiquen documentación. Un sistema de compilación puede generar automáticamente versiones HTML o PDF de la documentación a partir de archivos de texto sin formato para publicar en un sitio web o en un portal de documentación interno. Esto hace que la documentación sea accesible para más partes interesadas.
Al automatizar el proceso de generación y publicación de documentación, los documentos como código ayudan a reducir el tiempo y el esfuerzo necesarios para mantener y publicar la documentación. Permite que los equipos de desarrollo se concentren en mejorar el software.
Control de versiones
El almacenamiento de la documentación en el mismo repositorio de código que el software facilita la administración y el seguimiento de los cambios en ambos.
Puedes usar sistemas de control de versiones como Git para realizar un seguimiento de los cambios en la documentación y volver a las versiones anteriores si es necesario. Esto ayuda a garantizar que la documentación sea precisa y esté actualizada, y puede rastrear y auditar los cambios.
El flujo de trabajo típico de Documentos como código
El flujo de trabajo típico de documentos como código comprende la escritura, el control de versiones, la creación y el alojamiento:
El proceso de escritura
El proceso de escritura es la primera etapa de un flujo de trabajo típico de documentos como código. Mayoría escritores técnicos y los ingenieros de documentación usan MarkDown, AsciiDoc o HTML simples. Escriben la documentación utilizando herramientas como GitBook y Redocly que garantizan un proceso fluido.
Control de versiones para documentación
La documentación evoluciona a medida que evoluciona el código. Necesitará un sistema de control de versiones sofisticado como Git, Plastic SCM o Subversion para realizar un seguimiento de los cambios en la documentación y facilitar la colaboración y el seguimiento de versiones.
El proceso de creación de documentación
El proceso de construcción implica procesar y compilar la documentación en sus formatos de entrega. Estos pueden ser HTML, PDF, EPUB u otros. El proceso de documentación generalmente se facilita utilizando generadores de sitios estáticos como Hugo y Jekyll.
Hospedaje y Distribución de Documentación
El proceso de alojamiento o distribución suele ser el último paso de los documentos como proceso de codificación. Este proceso garantiza que la documentación se entregue al usuario final y esté disponible para todas las partes interesadas. Puede usar páginas de GitHub o GitLab o un portal personalizado para distribuir su documentación en la web.
Puede automatizar la documentación de Go y Java con GoDoc y JavaDoc
La filosofía docs as code está revolucionando la redacción y gestión de documentación técnica.
Muchos lenguajes de programación, incluidos Go y Java, brindan herramientas para automatizar la documentación mediante comentarios de código. Go proporciona la herramienta Godoc y Java proporciona JavaDoc.
