Empiece por el problema, no por Git
Docs-as-Code suele presentarse como Markdown, Git, pull requests, CI y un generador estático. La discusión entonces gira alrededor de herramientas antes de responder a la pregunta correcta: ¿qué está fallando en el flujo de documentación? Puede ser contenido obsoleto, revisiones lentas, términos inconsistentes, enlaces rotos o una publicación que depende de una sola persona.
El enfoque tiene sentido si reduce esos problemas. Si escribir se vuelve más difícil y la publicación sigue siendo manual, solo se ha cambiado una fricción por otra.
Qué incluye realmente Docs-as-Code
| Etapa | Qué ocurre | Variante simple | Variante más madura |
|---|---|---|---|
| Fuente | se cambia el contenido | Markdown/AsciiDoc en Git | contenido estructurado y esquema de metadatos |
| Edición | trabaja el autor | editor web de GitHub | github.dev, VS Code, IDE o interfaz de autor |
| Preview | se ve la página futura | build local/web | preview por cambio |
| Checks | la máquina encuentra rutina | enlaces + build | estilo, términos, API, accesibilidad, locales |
| Revisión | se valida el significado | un revisor | SME + revisión editorial |
| Publicación | se actualiza el sitio | build manual | CI/CD después de checks |
No hace falta llevar cada etapa al máximo nivel de complejidad. Elija el nivel mínimo que resuelva el riesgo real.
Un formato de texto no obliga a usar un IDE
GitHub permite editar un archivo directamente en el navegador. Para trabajo más largo, github.dev ofrece búsqueda, resaltado y control de cambios sin clone local. Así, un SME ocasional no tiene por qué aprender terminal, rebase o una build local.
| Participante | Suele bastar | No exigir sin motivo |
|---|---|---|
| Technical writer | github.dev, VS Code o editor preferido |
un IDE específico |
| SME ocasional | editor web + preview | terminal y rebase |
| Desarrollador | IDE + Git | una CMS separada si Markdown es más cómodo |
| Editor | navegador o authoring UI | conocer el pipeline internamente |
El formato canónico y la interfaz de edición son decisiones diferentes.
Flujo de trabajo de extremo a extremo
Cambio de producto → borrador → preview → checks automáticos → revisión técnica → revisión editorial → merge → publicación → control en producción.
En un equipo pequeño una persona puede cubrir varias funciones. No hace falta crear un pull request como ritual para cada errata. En equipos mayores conviene separar la verificación factual del SME y la responsabilidad del technical writer sobre tarea de usuario, estructura, terminología y claridad.
Qué comprobaciones conviene automatizar
| Check | Qué detecta | Resultado útil |
|---|---|---|
| Build | sintaxis, includes, templates | archivo y causa concreta |
| Enlaces internos | páginas o anchors eliminados | origen y destino |
| Metadatos | title, owner, locale, revision | campo que falta |
| Estructura | headings incorrectos | heading exacto |
| Terminología | términos prohibidos | término y reemplazo |
| Style lint | patrones editoriales | explicación breve y accionable |
| Ejemplos de código | sintaxis/formato | ejemplo y error |
| Contrato API | diferencias con schema/OpenAPI | field/endpoint afectado |
| Imágenes | asset, alt, tamaño | archivo y problema |
| Locales | idioma obligatorio ausente | artículo y locale |
| Secretos | tokens o claves | tipo de hallazgo sin imprimir el secreto |
Un warning que nadie piensa corregir debe mejorarse o eliminarse. El ruido enseña a ignorar la automatización.
Cuánto tiempo puede ahorrar
No existe un porcentaje universal y serio para Docs-as-Code. Es mejor calcularlo con supuestos visibles. Si hay 40 cambios al mes y cinco comprobaciones manuales consumen 20 minutos por cambio, son 13 h 20 min de rutina activa. Si después de automatizarlas se dedican 2 minutos por cambio a interpretar resultados, son 1 h 20 min.
Supuesto: 40 × 20 minutos frente a 40 × 2 minutos. Es un modelo de planificación, no un benchmark del sector.
La automatización industrial de revisión demuestra que quitar trabajo repetitivo puede tener impacto, pero no debemos trasladar sin más porcentajes de desarrollo de software a documentación.
Mida su propio efecto en vez de inventar un estudio
TechWriters no debería afirmar que ha estudiado varios proyectos hasta hacerlo de verdad. Para un experimento interno, mida durante cuatro semanas tiempo activo del autor, espera de review, tiempo de SME/editor, errores encontrados después de publicar, tiempo hasta producción y falsos positivos. Automatice después un conjunto concreto —por ejemplo enlaces, metadata y build— y repita.
Así se obtiene un caso real con contexto y límites, no una cifra decorativa.
Personas y máquinas deben revisar cosas distintas
| Máquina | Persona |
|---|---|
| existe el enlace | el destino es correcto para el usuario |
| existe el heading | la estructura responde a la tarea |
| el término está permitido | el término es comprensible |
| el ejemplo coincide con schema | el ejemplo enseña una tarea real |
| la página compila | la página ayuda a completar el trabajo |
Las comprobaciones con LLM pueden señalar contradicciones, pero los hechos deben confirmarse contra producto, especificación, prueba o experto responsable.
Dónde empieza el fanatismo
Empieza cuando la pureza del proceso importa más que las personas. Si un experto puede corregir un nombre en el navegador en dos minutos, no le obligue a instalar Node.js y aprender rebase. Mantenga una vía sencilla: edición web, issue, authoring asistido o una persona que lleve el cambio al repositorio.
Implante Docs-as-Code por etapas
- Semana 1: fuentes en Git e historial claro.
- Semana 2: preview y build automático.
- Semana 3: tres a cinco checks realmente útiles.
- Semana 4: separar revisión técnica y editorial cuando sea necesario.
- Después de un mes: medir lead time, rutina, errores y warnings ruidosos antes de añadir más herramientas.
Docs-as-Code funciona cuando reduce el coste de cambiar, revisar y publicar documentación.
