Documentación de software: qué exigir a tu equipo de desarrollo
La documentación de software es la diferencia entre ser dueño de tu sistema y alquilarlo a quien tiene el conocimiento. Qué exigir, y cómo saber si es buena, cuando no lees código.
Un founder con el que trabajamos heredó una base de código cuando su único desarrollador se fue con dos semanas de aviso. La app funcionaba bien. Ese era el problema. Nadie podía tocarla. No había una nota de cómo configurarla, ningún mapa de cómo encajaban las piezas, ningún registro de por qué el flujo de pago se había construido de esa forma rara. El siguiente desarrollador pasó cinco semanas haciendo ingeniería inversa de lo que unas pocas páginas de texto habrían explicado en una tarde. El founder pagó dos veces: una en honorarios, otra en el lanzamiento con el cliente que se retrasó.
La documentación de software es el registro escrito de cómo se construye, se opera y se mantiene un sistema. Son las instrucciones de configuración, el mapa de cómo se conectan las partes, las notas sobre por qué se tomaron decisiones clave y los pasos para operar y arreglar la cosa cuando se rompe. Para un founder no técnico, la documentación no es papeleo para ingenieros. Es el activo que convierte tu base de código de una caja negra que alquilas en algo que de verdad posees. Buena documentación significa que el siguiente desarrollador asume tu sistema en días. Documentación mala o inexistente significa que cada persona que alguna vez toque tu código te deja en una posición frágil.
Por qué esto te importa más a ti que a los ingenieros
Los ingenieros debaten la documentación como una cuestión de oficio. Para ti es una cuestión de control. Todo sistema sin documentar tiene exactamente una salida: la cabeza de quien lo construyó. Cuando esa persona se va, se enferma o simplemente olvida, el conocimiento se va con ella. Ese es el problema del bus factor, y la documentación es su seguro más barato.
También es la forma silenciosa del lock-in. Ya escribimos sobre cómo el vendor lock-in es un precio que pagas por quedarte. El código sin documentar es la misma trampa con otro traje. No estás atado a una plataforma; estás atado a una persona o a una software house, porque solo ellos pueden descifrar lo que existe. El día que quieras una segunda opinión, un equipo nuevo o un presupuesto justo para extender el producto, la ausencia de documentación es lo que encarece la salida.
Nada de esto exige que leas una línea de código. Exige que sepas qué documentos deberían existir y que insistas en que existan.
Los documentos que un founder debería exigir de verdad
Pídele a un ingeniero “los cuatro tipos de documentación” y recibirás una taxonomía que sirve a quien escribe documentación para vivir. Aquí va la versión que sirve a quien paga la construcción. Cinco documentos cubren casi todo lo que importa.
La guía de configuración, o README. Cómo un nuevo desarrollador pone el sistema a funcionar en su propia máquina, de principio a fin. Si un desarrollador competente no puede ir de cero a una copia local funcionando siguiendo este único archivo, está incompleto. Este es el documento más valioso, y el que más suele faltar.
La visión general de la arquitectura. Un mapa corto y en lenguaje sencillo de las partes principales y de cómo se hablan. Cuáles son los bloques principales, dónde viven los datos, qué pasa cuando un usuario hace la acción central. Dos o tres páginas y un diagrama. Es lo que permite a un nuevo desarrollador, o a un CTO fraccional que traigas, entender tu sistema sin leerlo todo antes.
Documentación de integraciones y de API. Cómo se conecta tu sistema al mundo exterior y cómo se conectan sus propias partes entre sí. De qué terceros dependes, qué se rompe si uno de ellos cambia, dónde viven las claves y credenciales (las referencias, no los secretos en sí). Es el mapa de tus dependencias, y en las dependencias es donde se esconden las sorpresas.
Runbooks de operación. Qué hacer cuando algo sale mal a las 2 de la mañana. Cómo hacer el deploy de un cambio, cómo restaurar desde un backup, cómo saber si el sistema está sano. Es la diferencia entre un incidente que dura veinte minutos y uno que dura un fin de semana.
Registros de decisión. Notas cortas sobre por qué se tomaron las decisiones no obvias. Por qué esta base de datos, por qué este proveedor de pagos, por qué el apaño raro en el checkout. Sin ellas, el siguiente desarrollador va a “limpiar” algo estructural y lo va a romper, porque nadie escribió que estaba ahí a propósito.
No necesitas que los cinco sean largos. Necesitas que existan y estén al día. Un README de una página que funciona vale más que un manual de cincuenta páginas que nadie actualizó desde la primera versión.
Cuánta documentación de software es suficiente
El instinto, una vez que un founder se quema, es exigir documentación de todo. Ese es un error en sí mismo. La documentación es código que hay que mantener, y documentar de más un producto nuevo que todavía cambia cada semana es un coste real con fecha de caducidad corta. Vas a pagar por escribir páginas que describen funciones que borras el mes siguiente.
La prueba honesta es una sola pregunta: ¿un desarrollador competente que nunca vio este sistema podría entregar un cambio pequeño y seguro en su primera semana, usando solo el material escrito y sin acceso a quien lo construyó? Si sí, tu documentación es suficiente para su etapa. Si no, tienes un hueco, y es exactamente tan caro como describió la sección anterior.
Los prototipos desechables apenas necesitan docs, porque piensas desecharlos. En el instante en que el código va a producción y un cliente real depende de él, la cuenta se invierte. Esa es la línea. Antes de ella, guarda notas. Después de ella, exige los cinco documentos.
Cómo distinguir buena documentación de teatro
No lees el código, así que no puedes calificar los docs directamente. Aun así puedes probarlos, y la prueba es barata. Cuando incorporas a un nuevo desarrollador o evalúas una empresa de desarrollo de software, entrégale tu documentación y tu base de código y pregúntale cuánto tardaría en hacer un cambio pequeño con seguridad. Una respuesta segura y específica, que cita tu guía de configuración real, es buena señal. La vaguedad, o una petición de “solo agenda una call con el desarrollador original”, te dice que la documentación no está haciendo su trabajo.
La otra señal es la actualidad. Abre la guía de configuración y compara la última vez que cambió con la última vez que cambió el código. Documentación que no se toca hace seis meses mientras el producto se entregó cada semana es decoración, no documentación. Los docs de verdad se actualizan en el mismo aliento que el código que describen. Pide a quien construye para ti que trate una actualización de documentación como parte de “terminado”, no como un favor que hará más tarde.
Write the Docs, la comunidad de profesionales de la documentación, resume el objetivo de forma simple: la documentación debe permitir que los lectores “tengan éxito por su cuenta”. Si tus docs no dejan que una persona nueva tenga éxito sin un tour guiado, no están terminados.
Quién la escribe, y cuánto debería costar
Quien escribe la documentación son las personas que construyen tu software. No un redactor técnico aparte, no tú, y no un becario traído al final para “documentar lo que existe”. El desarrollador que tomó una decisión es el único que puede explicarla de forma barata, y solo puede hacerlo mientras está fresca. Una semana después ya la medio olvidó; un mes después adivina como todos los demás.
Por eso la documentación debería costarte casi nada como partida. Un equipo competente la escribe como subproducto de la construcción, dentro de las mismas horas. Cuando una software house cotiza la documentación como una fase aparte y cara al final, léelo como una advertencia: normalmente significa que no documenta mientras construye, lo que significa que el resto del trabajo tiene la misma calidad hecha a posteriori. El coste correcto de una buena documentación es un impuesto pequeño pagado de forma continua, nunca una factura grande pagada de golpe al final.
Ponlo en el contrato, no en la esperanza
La forma fiable de conseguir documentación es exigirla antes de que empiece el trabajo, no pedirla después. Cuando acuerdas un alcance con un desarrollador o una software house, nombra los entregables. Un producto funcionando y los cinco documentos de arriba. Haz que “documentación al día” sea parte de lo que “terminado” significa en cada hito, igual que definirías cualquier otro criterio de aceptación en un contrato de alcance de trabajo.
Esto no te cuesta nada extra si lo dices desde el principio, porque un equipo competente documenta mientras trabaja. Cuesta una fortuna si lo pides al final, porque reconstruir el razonamiento detrás de seis meses de decisiones después del hecho es lento, mal recibido y a menudo solo adivinado. Los founders que nunca se queman con un desarrollador que se va son los que hicieron del mapa una condición de la construcción, no una esperanza para más tarde.
La documentación es la línea menos glamorosa de cualquier proyecto de software y la que decide, más que casi cualquier otra cosa, si lo que pagaste es un activo que posees o un pasivo que alquilas. Exige el mapa. Pagaste por el territorio.
Preguntas frecuentes
¿Qué significa documentación de software?
Es el registro escrito de cómo se construye, se opera y se mantiene un sistema de software: instrucciones de configuración, un mapa de cómo se conectan las partes, notas sobre por qué se tomaron decisiones clave y pasos para operar y arreglar. Para un founder no técnico, es lo que permite a un nuevo desarrollador asumir el sistema sin depender de quien lo construyó originalmente.
¿Cuál es un ejemplo de documentación de software?
El ejemplo más común y útil es un README: un único archivo que le dice a un nuevo desarrollador exactamente cómo poner el sistema a funcionar en su propia máquina, paso a paso. Otros ejemplos son una visión general de la arquitectura (un mapa en lenguaje sencillo de las partes principales), docs de integración (cómo se conecta a terceros), runbooks de operación (qué hacer cuando algo se rompe) y registros de decisión (por qué se tomaron decisiones no obvias).
¿Cuáles son los cuatro tipos de documentación?
Los ingenieros suelen nombrar tipos como tutoriales, guías prácticas, referencia y explicación. La versión que le importa a un founder que paga por la construcción son cinco documentos: una guía de configuración (README), una visión general de la arquitectura, docs de integración y de API, runbooks de operación y registros de decisión. Cubren el conocimiento que, de otro modo, viviría solo en la cabeza de un desarrollador.
¿Cuánta documentación necesita una startup pequeña?
La suficiente para que un desarrollador competente que nunca vio el sistema pueda entregar un cambio pequeño y seguro en su primera semana usando solo el material escrito. Por debajo de esa barra tienes un riesgo; por encima, probablemente estás documentando de más un producto que todavía cambia. Los prototipos desechables apenas necesitan docs; cualquier cosa de la que dependa un cliente que paga necesita el conjunto esencial.
¿Qué software tiene la mejor documentación?
Esa es una pregunta de herramienta, y es la equivocada para un founder. La calidad de tu documentación depende de la disciplina de quien la escribe, no de la herramienta en la que vive. Un README actual y claro en un wiki simple vale más que una plataforma de documentación sofisticada llena de páginas obsoletas. Juzga el hábito, no el software.
¿Cómo me aseguro de que mi desarrollador realmente documente?
Exígelo antes de que empiece el trabajo. Nombra los documentos como entregables en tu alcance de trabajo y haz que “documentación al día” sea parte de lo que “terminado” significa en cada hito. Un equipo competente documenta mientras construye, a casi ningún coste extra. Pedirlo solo al final es cuando la documentación se vuelve cara, mal recibida y poco fiable.