6. Principios de una buena documentación: claridad, precisión, completitud y utilidad
6.1 Introducción
Una documentación técnica puede existir y aun así no servir. Puede estar escrita, publicada y enlazada, pero ser confusa, incompleta, imprecisa o inútil para la tarea que el lector necesita realizar. Por eso, no alcanza con documentar: hay que documentar bien.
En este tema estudiaremos cuatro principios fundamentales: claridad, precisión, completitud y utilidad. Estos principios permiten evaluar la calidad de un documento técnico y tomar mejores decisiones al escribirlo, revisarlo o mantenerlo.
La buena documentación no depende solo de escribir correctamente. También depende de comprender la audiencia, el objetivo, el contexto, el sistema real y el uso que se dará al documento.
6.2 Qué significa buena documentación
Una buena documentación técnica es aquella que ayuda al lector a comprender, decidir o actuar con menor esfuerzo y menor riesgo. No se mide solamente por su extensión, cantidad de páginas o formato visual. Se mide por su capacidad para resolver una necesidad real.
Un documento breve puede ser excelente si permite ejecutar una tarea correctamente. Un documento largo puede ser malo si obliga al lector a buscar entre información desordenada. La calidad documental se evalúa desde el uso, no desde la cantidad de contenido acumulado.
6.3 Principios centrales
La imagen representa cuatro principios de una buena documentación técnica: claridad, precisión, completitud y utilidad. Cada principio aporta una condición distinta. La claridad permite entender. La precisión evita interpretaciones incorrectas. La completitud cubre lo necesario para el objetivo. La utilidad conecta el documento con una necesidad real.
6.4 Claridad
La claridad significa que el contenido puede entenderse sin esfuerzo innecesario. Un documento claro organiza las ideas, usa títulos significativos, evita frases confusas, define términos importantes y presenta la información en un orden lógico.
La claridad no implica simplificar de manera incorrecta. Un tema técnico puede ser complejo, pero debe explicarse de forma ordenada. Si el lector necesita releer varias veces una instrucción o no puede distinguir qué parte es condición, paso o resultado, la documentación necesita mejorar.
Para lograr claridad conviene usar oraciones directas, separar ideas largas, incluir ejemplos y evitar mezclar temas. También ayuda comenzar con el contexto antes de entrar en detalles.
6.5 Precisión
La precisión significa que el documento dice exactamente lo que debe decir. Evita afirmaciones vagas, términos ambiguos, instrucciones incompletas y generalizaciones que pueden interpretarse de distintas maneras.
Por ejemplo, escribir "el sistema responde rápido" no es preciso. Es mejor indicar una condición concreta, como "la búsqueda debe responder en menos de dos segundos para hasta mil registros". Escribir "el usuario puede cancelar con anticipación" tampoco es suficiente. Hay que indicar cuánta anticipación, quién puede cancelar y qué ocurre si la condición no se cumple.
La precisión es especialmente importante en requisitos, reglas de negocio, contratos de API, procedimientos operativos, configuración, seguridad y pruebas.
6.6 Completitud
La completitud significa que el documento contiene la información necesaria para cumplir su objetivo. No significa incluir todo lo posible, sino todo lo necesario. Un documento puede ser incompleto aunque sea largo, si omite condiciones, pasos, datos o excepciones importantes.
Una guía de instalación es completa si permite instalar el sistema desde cero, incluyendo requisitos previos, comandos, configuración y verificación. Una documentación de API es completa si permite consumir la API correctamente, incluyendo autenticación, parámetros, respuestas, errores y ejemplos.
La completitud depende de la audiencia. Un manual de usuario no necesita explicar la estructura de clases, pero sí debe incluir los pasos y mensajes que el usuario encontrará al realizar una tarea.
6.7 Utilidad
La utilidad significa que el documento resuelve una necesidad real. Un documento puede ser claro, preciso y completo, pero aun así aportar poco si nadie lo necesita o si no está orientado a una tarea, decisión o comprensión concreta.
La utilidad obliga a preguntar para qué existe el documento. ¿Ayuda a aprender? ¿Permite instalar? ¿Facilita modificar? ¿Evita errores? ¿Reduce consultas repetidas? ¿Registra una decisión importante? Si no hay una respuesta clara, probablemente el documento debe cambiar de foco o eliminarse.
6.8 Correctitud y actualidad
Además de los cuatro principios principales, una buena documentación debe ser correcta y estar actualizada. La correctitud significa que el contenido coincide con el sistema real. La actualidad significa que sigue siendo válida después de cambios en código, configuración, reglas o procesos.
Una documentación incorrecta puede ser peor que no tener documentación, porque genera confianza falsa. Un comando desactualizado, una regla vieja o un endpoint inexistente pueden causar errores, pérdida de tiempo y decisiones equivocadas.
Por eso, la documentación debe formar parte del proceso de cambio. Cuando cambia una funcionalidad, también deben revisarse los documentos relacionados.
6.9 Consistencia
La consistencia significa usar los mismos nombres, términos, formatos y criterios en documentos relacionados. Si una entidad se llama "Turno" en un documento, "Reserva" en otro y "Cita" en otro sin explicación, el lector puede pensar que son conceptos distintos.
La consistencia también aplica a estructura, estilo, ejemplos, formatos de fechas, nombres de estados, códigos de error y convenciones. Mantener consistencia facilita la búsqueda y reduce errores de interpretación.
Un glosario, una guía de estilo o plantillas comunes pueden ayudar a sostener esta calidad en equipos grandes.
6.10 Facilidad de búsqueda
Una documentación puede estar bien escrita, pero ser poco útil si nadie la encuentra. Por eso, la organización, los títulos, los enlaces y la navegación también forman parte de la calidad documental.
Los títulos deben describir el contenido real. Las secciones deben estar ordenadas. Los documentos relacionados deben enlazarse. Los nombres de archivo deben ser comprensibles. Si se usa una wiki, un sitio estático o un repositorio, la estructura debe ayudar a encontrar información por tema y por tarea.
6.11 Comparación de principios
| Principio | Pregunta de control | Problema si falla |
|---|---|---|
| Claridad | ¿Se entiende sin esfuerzo innecesario? | El lector se confunde o interpreta mal. |
| Precisión | ¿Dice exactamente lo necesario? | Aparecen ambigüedades e implementaciones distintas. |
| Completitud | ¿Incluye todo lo necesario para su objetivo? | El lector queda bloqueado o debe preguntar. |
| Utilidad | ¿Resuelve una necesidad real? | El documento existe, pero nadie lo usa. |
| Actualidad | ¿Coincide con el sistema actual? | Se toman decisiones con información vieja. |
6.12 Ejemplo de mejora: instrucción ambigua
Supongamos que una guía dice: "Configurar la base de datos antes de iniciar la aplicación". Esa instrucción es poco útil porque no indica qué base de datos, qué archivo modificar, qué valores son obligatorios ni cómo verificar que la configuración funciona.
Una versión mejor podría decir: "Antes de iniciar la aplicación, crear la base de datos turnos_dev, copiar el archivo .env.example como .env, completar las variables DB_HOST, DB_PORT, DB_NAME, DB_USER y DB_PASSWORD, y ejecutar la prueba de conexión indicada en la sección 3".
La segunda versión es más clara, precisa y completa. También es más útil porque permite actuar sin depender de una explicación externa.
6.13 Ejemplo de mejora: regla de negocio
Una regla escrita como "los turnos se pueden cancelar con anticipación" deja muchas dudas. No indica quién puede cancelar, cuánta anticipación se requiere, qué ocurre si el turno ya fue atendido ni si existen permisos especiales.
Una formulación más precisa sería: "Un paciente puede cancelar un turno hasta 24 horas antes de la fecha y hora programadas. Un administrador puede cancelar un turno en cualquier momento antes de que el estado sea Atendido. Cuando la cancelación no está permitida, el sistema debe mostrar un mensaje indicando el motivo".
Esta versión reduce ambigüedad y permite diseñar pruebas más claras.
6.14 Cómo revisar la calidad de un documento
Para revisar una documentación conviene leerla desde la perspectiva de su audiencia. Si es una guía, se puede intentar ejecutar los pasos desde cero. Si es una especificación, se pueden buscar ambigüedades. Si es una referencia técnica, se puede verificar que los ejemplos funcionen.
También es útil pedir revisión a otra persona. Quien escribió el documento suele conocer el tema y puede no detectar omisiones. Un lector nuevo encuentra más fácilmente instrucciones incompletas o términos no definidos.
6.15 Métricas y señales prácticas
Aunque la calidad documental tiene aspectos subjetivos, existen señales prácticas. Si muchas personas preguntan lo mismo, puede faltar documentación o estar mal ubicada. Si los procedimientos fallan con frecuencia, pueden estar incompletos. Si los documentos no se consultan, quizá no resuelven una necesidad real.
Otras señales son enlaces rotos, capturas desactualizadas, comandos que no funcionan, nombres inconsistentes, ejemplos sin contexto, documentos duplicados y ausencia de responsable de mantenimiento.
6.16 Errores frecuentes
Al buscar buena documentación suelen cometerse estos errores:
- Confundir cantidad de texto con calidad.
- Escribir frases largas y generales en lugar de instrucciones o reglas concretas.
- Omitir requisitos previos, condiciones o excepciones.
- No verificar que los ejemplos funcionen.
- Usar distintos nombres para el mismo concepto.
- Actualizar el sistema sin actualizar la documentación relacionada.
- Escribir documentos que no responden a una necesidad real.
6.17 Qué debes recordar de este tema
- Una buena documentación debe ser clara, precisa, completa y útil.
- La claridad facilita la comprensión.
- La precisión evita interpretaciones diferentes.
- La completitud incluye lo necesario para cumplir el objetivo del documento.
- La utilidad conecta la documentación con una necesidad real.
- La documentación también debe ser correcta, actualizada, consistente y fácil de encontrar.
- La calidad documental se verifica observando si la audiencia puede usar el contenido sin ayuda innecesaria.
6.18 Conclusión
Los principios de claridad, precisión, completitud y utilidad permiten escribir y evaluar documentación técnica con criterios concretos. Aplicarlos ayuda a producir documentos que no solo existen, sino que realmente mejoran la comunicación y reducen errores.
En el próximo tema estudiaremos la planificación documental: alcance, responsables, entregables y calendario.