29. Herramientas y formatos: Markdown, HTML, wikis, generadores estáticos y documentación como código

29.1 Introducción

La documentación técnica necesita contenido correcto, pero también necesita un formato y una herramienta adecuados. Si la documentación es difícil de editar, buscar, revisar o publicar, es probable que quede desactualizada aunque el contenido inicial haya sido bueno.

Existen muchas formas de documentar: archivos Markdown, páginas HTML, wikis, documentos compartidos, generadores estáticos, portales internos, especificaciones de API y documentación como código. Cada opción tiene ventajas y limitaciones.

En este tema veremos criterios para elegir herramientas y formatos según audiencia, mantenimiento, versionado, colaboración, publicación y relación con el código.

29.2 Por qué importa la herramienta

La herramienta no reemplaza al criterio técnico, pero influye en el mantenimiento. Una herramienta adecuada facilita escribir, revisar, buscar, enlazar, versionar y publicar. Una herramienta inadecuada agrega fricción y hace que el equipo evite actualizar documentos.

Por ejemplo, la documentación de API puede beneficiarse de una especificación formal. La documentación de arquitectura puede necesitar diagramas y decisiones versionadas. Un manual de usuario puede necesitar publicación web, navegación y búsqueda.

29.3 Ecosistema de herramientas y formatos

La imagen muestra un ecosistema de documentación técnica con Markdown, HTML, wikis, generadores estáticos, documentación como código, diagramas, especificaciones de API, control de versiones y publicación web.

29.4 Markdown

Markdown es un formato de texto liviano que permite escribir documentación con títulos, listas, enlaces, tablas, código e imágenes. Es muy usado en repositorios de código porque se lee bien como texto plano y se convierte fácilmente a HTML.

Es útil para README, guías técnicas, decisiones, documentación interna, notas de versión y páginas de sitios estáticos. Su principal ventaja es que se versiona bien y puede editarse con herramientas simples.

Su limitación aparece cuando se necesitan diseños complejos, control visual preciso o documentos formales con formato avanzado.

29.5 HTML

HTML permite publicar documentación como páginas web. Da más control sobre estructura, enlaces, estilos, tablas, imágenes y navegación. Es adecuado cuando se quiere una experiencia de lectura web o cuando el sitio ya está construido en HTML.

La ventaja de HTML es su compatibilidad universal. La desventaja es que puede ser más verboso de escribir manualmente. Por eso, muchas veces se genera HTML a partir de Markdown u otros formatos.

29.6 Wikis

Las wikis permiten crear y editar páginas de forma colaborativa. Son útiles para documentación interna, conocimiento compartido, procedimientos, preguntas frecuentes y documentación que cambia con frecuencia.

Su ventaja es la facilidad de edición y enlace entre páginas. Su riesgo es el desorden: si no hay estructura, responsables y revisión, la wiki puede transformarse en un conjunto de páginas duplicadas o desactualizadas.

29.7 Generadores estáticos

Los generadores estáticos convierten archivos fuente, como Markdown, en un sitio web navegable. Permiten combinar escritura simple con publicación ordenada, temas visuales, búsqueda, menús y enlaces.

Son útiles para cursos, portales de documentación, manuales técnicos, documentación de producto y documentación para desarrolladores. También facilitan publicar versiones y automatizar despliegues.

29.8 Documentación como código

Documentación como código significa tratar la documentación con prácticas similares al software: archivos en repositorio, control de versiones, revisión por pares, ramas, solicitudes de cambio, automatización y publicación continua.

Este enfoque es especialmente útil cuando la documentación cambia junto con el código: README, APIs, arquitectura, decisiones, guías de instalación, pruebas y despliegue.

29.9 Control de versiones

El control de versiones permite saber cuándo cambió un documento, quién lo modificó y por qué. También permite revisar cambios, recuperar versiones anteriores y relacionar documentación con cambios de código.

Es especialmente valioso para documentación técnica interna, decisiones de arquitectura, especificaciones de API y guías de despliegue. Si el documento describe una versión del sistema, debe quedar claro a qué versión corresponde.

29.10 Especificaciones de API

Para APIs, conviene usar formatos estructurados como OpenAPI cuando sea posible. Estos formatos permiten describir endpoints, parámetros, respuestas y errores de manera legible para personas y herramientas.

Con una especificación formal se puede generar documentación navegable, validar contratos, crear clientes, probar respuestas y reducir diferencias entre implementación y documentación.

29.11 Diagramas como código

Algunos diagramas pueden escribirse en texto usando herramientas como Mermaid o PlantUML. Esto facilita versionado, revisión y generación automática dentro de sitios de documentación.

No todos los diagramas necesitan este enfoque. Para bocetos rápidos puede alcanzar una herramienta visual. Pero si el diagrama es parte estable de la documentación técnica, escribirlo como código puede ayudar a mantenerlo.

29.12 Búsqueda y navegación

Una herramienta de documentación debe facilitar encontrar información. Esto incluye menús, índices, buscador, etiquetas, enlaces, rutas claras y títulos descriptivos.

Cuando la documentación crece, la búsqueda se vuelve tan importante como el contenido. Un documento correcto pero escondido puede no ser usado.

29.13 Publicación y permisos

No toda documentación debe tener la misma visibilidad. Un manual de usuario puede ser público. Una guía interna de operación puede requerir acceso controlado. La documentación de seguridad puede necesitar restricciones más fuertes.

La herramienta debe permitir publicar a la audiencia correcta y controlar permisos cuando sea necesario. También debe facilitar actualización sin procesos manuales excesivos.

29.14 Tabla comparativa

29.15 Criterios de elección

Para elegir herramienta y formato conviene evaluar audiencia, frecuencia de cambios, necesidad de versionado, permisos, búsqueda, colaboración, publicación, automatización y cercanía con el código.

Si la documentación cambia con el código, conviene acercarla al repositorio. Si la documentación está orientada a usuarios finales, conviene priorizar navegación y publicación. Si contiene conocimiento operativo interno, conviene equilibrar acceso rápido y control de permisos.

29.16 Errores frecuentes

Al elegir herramientas de documentación suelen aparecer estos errores:

• Elegir una herramienta por moda y no por necesidad real.
• Separar documentación del código cuando cambia junto con él.
• Usar una wiki sin estructura ni responsables.
• No controlar permisos de documentación sensible.
• No automatizar publicación cuando el proceso se repite con frecuencia.
• No definir nombres, carpetas y enlaces consistentes.
• Creer que la herramienta resolverá problemas de contenido y mantenimiento.

29.17 Qué debes recordar de este tema

• La herramienta influye en edición, revisión, búsqueda, publicación y mantenimiento.
• Markdown es simple y adecuado para documentación versionada.
• HTML permite publicación web flexible.
• Las wikis facilitan colaboración, pero necesitan estructura.
• Los generadores estáticos permiten crear sitios de documentación ordenados.
• La documentación como código acerca documentos y cambios técnicos.
• La elección debe depender de audiencia, frecuencia de cambios, permisos y mantenimiento.

29.18 Conclusión

Herramientas y formatos no garantizan buena documentación, pero pueden facilitar o dificultar su mantenimiento. Elegir bien permite que el contenido se escriba, revise, publique y actualice con menos fricción.

En el próximo tema estudiaremos el control de versiones de la documentación y su relación con el código fuente.