Documentación técnica: casi todas las empresas dicen que la valoran. Muy pocas la ejecutan bien. En Novalca hemos revisado decenas de equipos de desarrollo y operaciones que acumulan wikis, PDFs y documentos compartidos que nadie abre desde hace meses. Y el problema, casi nunca, es la falta de documentación. Es que la que existe no responde a las preguntas reales del equipo cuando las tiene. Aquí comparto lo que he aprendido creando y depurando documentación en proyectos de hosting, desarrollo y automatización, con ejemplos que puedes aplicar esta misma semana.
Por qué la documentación técnica que nadie usa es un problema caro
La documentación que no se consulta no es neutra. Es un coste activo. Está, primero, el tiempo invertido en escribirla, que puede superar sin problema las decenas de horas por proyecto. Pero el coste de verdad es otro: el que aparece cuando alguien no la usa.
- Tiempo de onboarding alargado. Hemos visto incorporaciones que se estiran de dos semanas a dos meses porque el desarrollador nuevo acaba preguntándolo todo por Slack en vez de encontrarlo documentado.
- Conocimiento concentrado en una persona. Cuando solo el técnico senior sabe cómo funciona el despliegue del cliente X, cada vacaciones o baja es un riesgo operativo. Nos pasó con un proceso de migración de servidores que vivía exclusivamente en la cabeza de un compañero durante años.
- Errores repetidos. Si el procedimiento correcto no está a mano, cada persona improvisa su propia versión. En entornos de hosting, eso se traduce en configuraciones inconsistentes y tickets de soporte evitables.
Haz la cuenta rápida. Un equipo de cinco desarrolladores que pierde tres horas semanales buscando información que existía pero no era localizable: más de 700 horas al año. La documentación mala no ahorra tiempo. Lo destruye, silenciosamente.
El error número uno: escribir para archivar, no para consultar
El error más común que he visto en todos estos años es escribir documentación pensando en «dejar constancia» en lugar de pensar en el momento de uso. Dos mentalidades opuestas:
- Documentar para archivar: se escribe al final del proyecto, se describe todo el sistema de forma enciclopédica, se usa el punto de vista del que ya lo conoce y se da por terminada en el momento de publicarla.
- Documentar para consultar: se escribe pensando en la pregunta concreta que alguien tendrá a las tres de la mañana cuando el servidor se caiga. Prioriza lo frecuente sobre lo completo, y se revisa constantemente.
Un ejemplo real. Durante años mantuvimos un documento de 40 páginas sobre nuestra infraestructura. Impecable, completo, ordenado. Y prácticamente nadie lo consultaba, porque buscar una respuesta en él costaba más que preguntar a un compañero. Lo sustituimos por una página corta con los diez procedimientos más frecuentes, cada uno resoluble en dos minutos. El uso se disparó. La documentación larga no es mejor documentación; muchas veces es, directamente, documentación inaccesible.
Regla práctica: si un documento no tiene un lector y una situación de uso identificables («el técnico de guardia restaurando una copia de seguridad»), no está terminado. Está decorado.
Cómo estructurar la documentación técnica según quien la va a usar
La segunda causa de documentación ignorada es la homogeneidad: un mismo formato para lectores distintos. Un desarrollador que integra una API, un técnico de soporte y un empleado recién llegado no necesitan lo mismo, ni de lejos. Antes de escribir una línea, identifica para quién es el documento y qué quiere conseguir quien lo abre. En Novalca separamos la documentación en tres niveles:
- Guías de referencia (para quien ejecuta): procedimientos paso a paso, comandos exactos, capturas de los estados intermedios. Cero contexto innecesario. Ejemplo: «Cómo restaurar una copia de seguridad en cPanel», con el orden exacto de pasos y qué verificar al final.
- Documentos de decisión (para quien mantiene): explican por qué se eligió una arquitectura, qué alternativas se descartaron y qué deudas técnicas se aceptaron. Este nivel es el que casi nadie documenta y, curiosamente, el que más dolores evita seis meses después.
- Onboarding (para quien llega): cómo montar el entorno local, dónde está cada cosa, a quién preguntar. Corto y orientado a tener algo funcionando el primer día.
Una estructura mínima que funciona
Para cada documento, usa un esqueleto simple: qué es esto y para quién es en las dos primeras líneas, cuándo usarlo, los pasos o la explicación y, al final, qué hacer si falla. Ese último apartado, el de fallos comunes, es el que multiplica el valor del documento. La mayoría de las consultas surgen exactamente ahí. Y añade siempre una fecha de última revisión; un documento sin fecha es un documento en el que nadie confía.
Empieza pequeño. Elige los tres procedimientos que tu equipo consulta con más frecuencia y reescríbelos con este enfoque. Verás el cambio en la adopción antes de haber documentado ni el 10% de tu sistema.
Herramientas y formatos que facilitan el consumo (no solo la creación)
Hay un fallo clásico aquí: elegir la herramienta pensando en quien escribe, no en quien lee. Nos ha pasado. Hemos probado wikis corporativas, Notion, Confluence, Google Docs y hasta un simple repositorio de Markdown. Y la conclusión, tras años, es incómoda: la marca del software da casi igual. Lo que importa es si la persona que busca una respuesta la encuentra en menos de 30 segundos.
Cuando digitalizamos procesos en Novalca acabamos valorando tres cosas por encima de cualquier funcionalidad avanzada:
- Búsqueda potente: si el motor no encuentra «cómo restaurar un backup» cuando alguien escribe «recuperar copia», la documentación está muerta. Pruébala con las palabras que usa tu equipo, no las que usarías tú.
- Lectura en móvil: muchas consultas técnicas ocurren fuera del escritorio. En el datacenter, de guardia, en un pasillo. Un formato que solo se lee bien en pantalla grande falla justo cuando más se necesita.
- Enlaces permanentes por sección: poder compartir el enlace directo al paso 4 de un procedimiento evita capturas de pantalla por Slack y respuestas desactualizadas. Parece un detalle. No lo es.
En cuanto al formato, la regla que mejor nos funciona es simple: pasos numerados para procedimientos, estructuras de referencia para catálogos (APIs, configuraciones, credenciales de entorno) y diagramas solo cuando el flujo tiene ramificaciones. Un diagrama de una línea recta es un documento disfrazado. Y con los vídeos, cuidado. Son imposibles de buscar y de actualizar. Un vídeo de diez minutos sin transcripción obliga a quien consulta a verlo entero para localizar un dato de treinta segundos.
Consejo práctico: antes de adoptar una herramienta nueva, haz la prueba del becario. Pídele a alguien que no participó en la redacción que resuelva una incidencia real usando solo la documentación. Cronométralo. Ese tiempo es tu métrica real de calidad.
Cómo conseguir que el equipo contribuya y mantenga la documentación
Aquí mueren la mayoría de proyectos de documentación técnica. El documento inicial se escribe con entusiasmo y seis meses después describe un sistema que ya no existe. Todos lo sabemos. La solución no es exigir más disciplina, sino reducir la fricción y alinear incentivos.
Tres tácticas que nos han funcionado:
- Documentar forma parte de la tarea, no una tarea aparte. Si la definición de «hecho» de un ticket incluye actualizar la página afectada, la documentación se mantiene sola. Si se deja «para después», después nunca llega. Nunca.
- Repartir la propiedad. Cada documento necesita un responsable claro, con nombre y apellidos. La documentación «de todos» no es de nadie, y las páginas huérfanas son las primeras que caducan.
- Premiar las correcciones, no castigarlas. Cuando alguien edita un documento porque estaba mal, eso es una victoria, no un reproche al autor original. En nuestro equipo, quien corrige una instrucción errónea recibe el mismo reconocimiento que quien resuelve la incidencia, porque evitó las siguientes veinte.
También ayuda dejar constancia de la fecha de revisión en cada documento y programar una revisión trimestral ligera de solo los documentos marcados como críticos. Quince minutos al mes por persona. Con eso basta para que el conjunto respire actualidad.
Conclusión: menos documentos, más respuestas
La documentación técnica no es un fin, es un medio. El objetivo nunca fue «tener documentado el sistema», sino que cualquier persona del equipo —y tu yo del futuro— encuentre respuestas rápidas sin interrumpir a otros. Cada documento debe medirse por las preguntas que resuelve. No por su extensión ni por su elegancia.
¿Por dónde empezar? Por lo que más duele: los tres procedimientos que generan más consultas repetidas. Escríbelos para quien los va a leer, con formato consumible, un responsable y una fecha de revisión. Luego deja que el uso real te diga qué documentar después. En pocos meses dejarás de responder las mismas preguntas por chat, y tu equipo ganará algo más valioso que cualquier herramienta: autonomía.