Cómo documentar tu web para no depender de nadie

Documentar una web es una de esas tareas que casi nadie hace hasta que llega el momento en que la necesita: cuando cambia de proveedor, cuando un desarrollador abandona el proyecto, cuando algo se rompe y nadie sabe por qué se configuró así. La documentación no es burocracia; es la memoria operativa de tu proyecto digital.

Por qué la mayoría de webs no tienen documentación

La razón más común es la presión del tiempo. Cuando se lanza un sitio, el equipo está ocupado en hacer que todo funcione. La documentación queda para después, y ese después raramente llega. El problema es que cada semana que pasa sin documentar, más contexto se pierde. Las decisiones que se tomaron tienen sentido en el momento; seis meses después, nadie recuerda por qué se eligió ese plugin, por qué la estructura de URLs es así o qué hace ese script en el footer.

Hay también una creencia implícita, especialmente entre agencias y freelances, de que no documentar crea dependencia. Si solo el desarrollador sabe cómo funciona la web, el cliente tiene más dificultades para marcharse. Es una estrategia cortoplacista que daña la confianza y, a largo plazo, la reputación del proveedor.

El resultado en ambos casos es el mismo: una web que nadie entiende del todo, donde cada intervención conlleva riesgo porque se trabaja a ciegas.

Qué debe incluir la documentación de una web

No existe un estándar universal, pero hay una serie de bloques que cualquier documentación mínimamente útil debería cubrir. El nivel de detalle puede variar según el tamaño del proyecto, pero los bloques son los mismos.

Información general del proyecto

El punto de partida es un documento que recoja los datos básicos: nombre del proyecto, URL de producción, URL de staging si existe, fecha de lanzamiento, tecnologías usadas (CMS, framework, base de datos) y las personas o empresas involucradas con sus roles. Esto parece trivial, pero cuando alguien nuevo entra al proyecto agradece tenerlo en un solo lugar en lugar de buscarlo en correos o Slack.

También conviene anotar dónde está alojada la web y bajo qué plan, porque los detalles del servidor afectan a decisiones técnicas posteriores. Si alguna vez necesitas saber si tu infraestructura aguantará un pico de visitas, toda esa información importa. Hay una guía útil para entender cuándo merece la pena pagar por un hosting gestionado que puede ayudarte a contextualizar esas decisiones.

Accesos y credenciales

Este bloque es el más sensible y también el más urgente. Hosting, panel de administración, FTP o SSH, base de datos, servicios de terceros (pasarela de pago, email transaccional, Analytics, Search Console), dominio y DNS. Todo debe estar registrado en un gestor de contraseñas compartido o en un documento con acceso restringido, nunca en un hilo de correo o en un chat.

La recomendación concreta: usa un gestor como Bitwarden, 1Password o Keeper con bóvedas separadas por proyecto. Así los accesos sobreviven a cambios de personal y no dependen de que nadie recuerde dónde los guardó.

Arquitectura y estructura del sitio

Aquí se documenta cómo está construida la web por dentro. Las plantillas o temas utilizados, los plugins activos con su versión y su función específica (no solo el nombre), la estructura de directorios si hay modificaciones relevantes, y los hooks o personalizaciones aplicadas al código base.

Este apartado es especialmente valioso cuando llega alguien nuevo. Sin él, el desarrollador de turno tiene que deducir para qué sirve cada pieza, lo que multiplica el tiempo de cada intervención y el riesgo de romper algo. Elegir bien los plugins desde el principio facilita mucho esta tarea; si quieres entender qué criterios aplicar, vale la pena revisar cómo elegir plugins sin comprometer el rendimiento.

Flujos de trabajo y procesos habituales

Cómo se publica contenido nuevo, cómo se hacen los backups y cada cuánto, cómo se despliegan cambios, qué entorno de pruebas existe y cómo acceder a él. Estos procesos suelen vivir solo en la cabeza del que los realiza, y cuando esa persona no está disponible todo se detiene.

Documentar el proceso de backup es especialmente importante. Una mala recuperación de datos puede costar mucho más que haberla documentado. La estrategia 3-2-1 aplicada a copias de seguridad web es un buen punto de partida para estructurar ese apartado.

Decisiones técnicas y su justificación

Este bloque es el que más se omite y el que más valor tiene. No basta con documentar qué se hizo; hay que documentar por qué. Por qué se eligió ese CDN y no otro, por qué las imágenes se sirven desde un subdominio, por qué se desactivó el renderizado en cliente para ciertas páginas.

Sin ese contexto, un desarrollador futuro puede revertir una decisión costosa creyendo que fue un error, cuando en realidad respondía a un problema concreto. Si tienes dudas sobre cómo afectan esas decisiones al posicionamiento, entender cómo el renderizado JavaScript impacta en el SEO te dará argumentos para documentarlas con criterio.

Cómo organizarla para que sea útil

Una documentación que nadie consulta porque es difícil de navegar vale lo mismo que no tenerla. La organización importa tanto como el contenido.

La opción más práctica para proyectos pequeños y medianos es una wiki interna. Notion, Confluence, Obsidian o incluso un repositorio de Git con archivos Markdown funcionan bien. Lo que importa es que la estructura sea predecible: alguien que no conoce el proyecto tiene que encontrar lo que busca en menos de dos minutos.

Un índice claro al principio, secciones numeradas y un sistema de etiquetas por área (accesos, técnico, procesos, histórico) ayudan mucho. Si usas Git para el código, considera incluir un archivo README.md en el repositorio con al menos el resumen técnico: tecnologías, requisitos del entorno, instrucciones de instalación local y enlace al resto de la documentación.

Documenta en el momento en que haces la tarea, no después. El «ya lo escribo luego» es el mayor enemigo de la documentación. Si instalas un plugin hoy, anótalo hoy. Si cambias una configuración de DNS, escribe por qué. El coste marginal de documentar en tiempo real es mínimo; el coste de reconstruirlo desde cero semanas después es mucho mayor.

La documentación durante una migración o cambio de proveedor

El momento en que más se nota la ausencia de documentación es durante una migración. Cambiar de hosting, de CMS o de agencia sin documentación previa convierte un proceso técnico en un trabajo de arqueología. Se pasan horas deduciendo configuraciones, chequeando si algo estaba personalizado o si era la instalación por defecto, y verificando que nada se ha roto por el camino.

Con una documentación actualizada, una migración bien planificada puede ejecutarse con mucha más seguridad. Si estás en ese proceso, revisar cómo migrar sin perder posicionamiento te ayudará a no descuidar la parte SEO mientras gestionas la parte técnica.

También conviene documentar el estado de la web antes de la migración como un snapshot: versiones de software, configuraciones activas, redireccionamientos existentes, plugins instalados. Ese registro sirve como referencia comparativa para verificar que el resultado final es equivalente al original.

Documentación de seguridad y mantenimiento

Un apartado específico para seguridad ahorra tiempo y reduce el pánico cuando algo va mal. Qué firewall está activo, qué reglas se han configurado, qué usuarios tienen acceso de administrador y desde cuándo, si hay autenticación en dos factores activada y para quién. Cuando recibes un aviso de intrusión o un plugin vulnerable, tener esa información accesible inmediatamente hace la diferencia.

Del mismo modo, la documentación de mantenimiento recurrente (actualizaciones, auditorías, revisiones de rendimiento) permite delegar esas tareas sin explicar cada vez desde cero qué hay que hacer y en qué orden. Si quieres estructurar bien esa parte, una referencia útil es entender qué incluye el mantenimiento web para saber qué procesos necesitan quedar por escrito.

La checklist de seguridad también merece su propio espacio en la documentación. No como un documento genérico descargado de internet, sino como el registro de qué controles específicos se han aplicado a esa instalación concreta. Puedes tomar como referencia una checklist de seguridad para WordPress y adaptarla a tu caso, documentando qué se ha hecho y cuándo.

Cuándo revisar y actualizar la documentación

La documentación desactualizada es casi peor que no tenerla, porque genera una falsa sensación de seguridad. Hay que establecer revisiones periódicas, no como una promesa vaga sino como un proceso con fecha y responsable.

Una revisión trimestral es razonable para la mayoría de proyectos. En esa revisión se comprueba que los accesos siguen siendo correctos, que los plugins documentados coinciden con los instalados, que los procesos descritos reflejan lo que realmente se hace. También es el momento de añadir las decisiones técnicas tomadas en los últimos meses que no se documentaron en su momento.

Un truco práctico: cada vez que alguien del equipo tiene que buscar información que no está en la documentación, ese hueco se convierte en una tarea de escritura. Si tuviste que preguntar a alguien para encontrar la respuesta, documenta la respuesta para que no haya que volver a preguntar.

Empieza con un documento de una página

Si tu web lleva tiempo funcionando sin ninguna documentación, el primer paso no es montar una wiki completa. Es demasiado ambicioso y probablemente no llegará a hacerse. Empieza con un documento de una sola página que recoja los accesos principales, las tecnologías usadas y el nombre de la persona que sabe más del proyecto.

Ese documento mínimo ya reduce el riesgo de forma significativa. A partir de ahí, se va ampliando de forma incremental: cada intervención técnica deja un registro, cada proceso nuevo se escribe cuando se define. En tres o cuatro meses, tendrás una documentación operativa sin haber dedicado ni un solo día completo a crearla desde cero.

Antes de dar ese primer paso, puede ser útil hacer una auditoría completa del estado actual de tu web: te dará una imagen real de lo que hay que documentar y te evitará escribir sobre configuraciones que ya no están activas.