Documentación como Código
Práctica de tratar la documentación con las mismas herramientas y procesos que el código: versionada en Git, revisada en PRs, y generada automáticamente cuando es posible.
¿Qué es?
Documentation as Code es la práctica de tratar la documentación como código: vive en el mismo repositorio, se versiona con Git, se revisa en pull requests, y se genera/valida automáticamente en CI.
Principios
| Principio | Qué significa | Ejemplo |
|---|---|---|
| Colocación | Docs cerca del código que documentan | README en cada paquete, JSDoc en funciones |
| Versionado | La documentación evoluciona con el código | Docs en el mismo repo, mismos PRs |
| Automatización | Generar docs de código cuando sea posible | TypeDoc, Swagger/OpenAPI, Storybook |
| Validación | Verificar links, ejemplos, formato en CI | Markdown lint, link checker en CI |
Herramientas
| Herramienta | Uso |
|---|---|
| Markdown | Formato universal |
| MDX | Markdown + componentes React |
| Docusaurus | Sitios de documentación |
| Storybook | Documentación de componentes |
| TypeDoc/JSDoc | Docs generadas de código |
| OpenAPI | Docs de API generadas |
Conexión con llms.txt
El estándar llms.txt es documentación como código optimizada para agentes de IA — un archivo Markdown que describe el proyecto para consumo por LLMs.
¿Por qué importa?
La documentación que vive separada del código se desactualiza inevitablemente. Tratarla como código — versionada en Git, revisada en PRs, generada desde fuentes autoritativas — es la única forma de mantenerla sincronizada con la realidad del sistema.
Referencias
- Docs as Code — Write the Docs.
- MkDocs — MkDocs, 2024. Generador de sitios de documentación desde Markdown.
- Docusaurus — Meta, 2024. Framework de documentación con versionado y i18n.
Contenido relacionado
- Desarrollo Dirigido por Especificación
Metodología de desarrollo donde la especificación se escribe antes del código, sirviendo como contrato entre equipos y como fuente de verdad para la implementación.
- llms.txt
Estándar propuesto para publicar un archivo Markdown en la raíz de un sitio web que permite a los modelos de lenguaje entender y utilizar el contenido del sitio de forma eficiente durante la inferencia.
- Plantillas Copier DraftMK
Plantillas Copier para scaffolding de proyectos con Docker Compose, documentación MkDocs y configuración automatizada.
- Onboarding de Desarrolladores
Proceso estructurado para que nuevos desarrolladores se vuelvan productivos rápidamente, desde setup del entorno hasta comprensión de la arquitectura y procesos del equipo.