4. Objetivos de la documentación: informar, guiar, registrar decisiones y reducir ambigüedad

4.1 Introducción

La documentación técnica no se escribe solo para acumular información. Cada documento debería tener un objetivo claro. Si el objetivo no está definido, el contenido suele crecer sin orden, mezcla temas distintos y termina siendo difícil de usar.

En proyectos de software, la documentación técnica suele cumplir cuatro objetivos principales: informar, guiar, registrar decisiones y reducir ambigüedad. Estos objetivos pueden aparecer separados o combinados, pero conviene reconocerlos porque influyen en la estructura, el lenguaje y el nivel de detalle del documento.

Por ejemplo, una descripción de arquitectura informa cómo está organizado el sistema. Una guía de instalación orienta paso a paso. Un registro de decisiones explica por qué se eligió una solución. Una especificación funcional reduce ambigüedad sobre reglas y comportamientos esperados.

4.2 Por qué definir el objetivo antes de escribir

Definir el objetivo permite decidir qué incluir, qué dejar fuera y cómo ordenar el contenido. No se escribe de la misma forma un documento para aprender un tema, una guía para ejecutar un procedimiento, un registro histórico de decisiones o una especificación que debe evitar interpretaciones diferentes.

Cuando un documento no tiene objetivo, el lector no sabe qué esperar. Puede encontrar explicaciones generales cuando necesita pasos concretos, o detalles técnicos cuando solo busca una visión general. Esa falta de foco reduce la confianza en la documentación.

4.3 Objetivos principales de la documentación

La imagen representa cuatro objetivos centrales de la documentación técnica: informar, guiar, registrar decisiones y reducir ambigüedad. En el centro aparece la documentación como herramienta de trabajo; alrededor, cada objetivo muestra una función distinta dentro del proyecto de software.

4.4 Informar

Informar significa presentar conocimiento de manera ordenada para que el lector comprenda un tema. Este objetivo aparece en documentos que explican qué es un sistema, qué partes lo componen, qué funcionalidades ofrece, qué conceptos maneja o cómo está organizada una solución.

Un documento informativo no necesariamente indica pasos a seguir. Su propósito principal es construir comprensión. Por ejemplo, una visión general del sistema puede explicar módulos, actores, procesos principales, límites, integraciones y responsabilidades. Un glosario puede informar el significado de términos usados por el dominio. Una descripción de arquitectura puede explicar componentes y relaciones.

Para informar bien, la documentación debe ordenar la información desde lo general hacia lo particular. Primero conviene explicar el contexto y luego los detalles. Si se empieza directamente con excepciones, configuraciones o casos complejos, el lector puede perderse.

4.5 Guiar

Guiar significa acompañar al lector para que pueda completar una tarea. Este objetivo aparece en manuales, tutoriales, guías de instalación, procedimientos de despliegue, instructivos de operación y recetas técnicas.

Una guía debe ser concreta, secuencial y verificable. Debe indicar requisitos previos, pasos, comandos, datos necesarios, resultados esperados y posibles problemas. A diferencia de un documento informativo, una guía se evalúa por su capacidad para permitir que el lector haga algo.

Por ejemplo, una guía de instalación debería permitir preparar un entorno desde cero. Una guía de uso debería permitir reservar un turno sin ayuda externa. Un procedimiento de recuperación debería indicar qué hacer ante una falla específica y cómo comprobar que el sistema volvió a funcionar.

4.6 Registrar decisiones

Registrar decisiones significa dejar constancia de una elección técnica o funcional importante. En los proyectos de software se toman muchas decisiones: usar una base de datos determinada, separar un módulo, exponer una API, aplicar una política de seguridad, aceptar una restricción o posponer una mejora.

Si esas decisiones no se registran, el equipo puede olvidar el motivo original. Meses después, una elección puede parecer incorrecta simplemente porque ya no se recuerda el contexto. Documentar decisiones ayuda a entender qué alternativas existían, qué criterio se aplicó y qué consecuencias se aceptaron.

Un buen registro de decisión no necesita ser extenso, pero debe incluir el problema, la decisión tomada, el motivo, las alternativas consideradas, las consecuencias y la fecha aproximada. Esto facilita revisar la decisión en el futuro si el contexto cambia.

4.7 Reducir ambigüedad

Reducir ambigüedad significa evitar interpretaciones diferentes sobre un mismo tema. Este objetivo es fundamental en requisitos, reglas de negocio, contratos de API, criterios de aceptación, formatos de datos, permisos, estados y validaciones.

Una frase ambigua puede generar implementaciones distintas. Por ejemplo, decir "el usuario puede cancelar un turno con anticipación" no alcanza. ¿Cuánta anticipación? ¿Todos los usuarios? ¿Qué ocurre si el turno ya fue confirmado? ¿Qué mensaje debe mostrarse? ¿Hay excepciones para administradores?

La documentación reduce ambigüedad cuando define condiciones, límites, ejemplos, casos especiales y resultados esperados. No se trata de escribir más palabras, sino de precisar lo que puede generar dudas.

4.8 Diferencias entre informar y guiar

Informar y guiar son objetivos relacionados, pero no equivalentes. Un documento informativo explica un tema. Una guía permite ejecutar una tarea. El lector de un documento informativo busca comprender. El lector de una guía busca hacer.

Por ejemplo, un documento que explica qué es el despliegue continuo informa. Un procedimiento que indica cómo publicar una nueva versión guía. Ambos pueden coexistir, pero si se mezclan sin orden, el lector puede no encontrar lo que necesita.

4.9 Documentos con objetivos combinados

En la práctica, muchos documentos combinan objetivos. Una guía de despliegue puede informar brevemente sobre ambientes y luego guiar con pasos. Una documentación de API puede informar conceptos generales, guiar con ejemplos y reducir ambigüedad con contratos precisos. Un documento de arquitectura puede informar la estructura y registrar decisiones.

Combinar objetivos no es un problema si el documento está bien organizado. Lo importante es separar secciones y no mezclar estilos. Una introducción puede explicar contexto, una sección de procedimiento puede enumerar pasos y una sección de decisiones puede justificar alternativas.

4.10 Objetivo y audiencia

El objetivo de la documentación siempre se relaciona con la audiencia. Un mismo documento puede fracasar si intenta servir a todos los lectores y todos los objetivos al mismo tiempo. Una guía para usuarios finales no debería convertirse en una explicación de arquitectura. Una referencia de API no debería depender de una descripción comercial del producto para entenderse.

Definir audiencia y objetivo juntos permite escribir con foco. Por ejemplo: "esta guía sirve para que un nuevo desarrollador pueda ejecutar el proyecto en su equipo"; "este documento sirve para que soporte pueda diagnosticar errores de inicio de sesión"; "esta especificación sirve para que desarrollo y pruebas entiendan la regla de cancelación".

4.11 Objetivo y nivel de detalle

El nivel de detalle depende del objetivo. Para informar, puede bastar una descripción conceptual. Para guiar, se necesitan pasos concretos y resultados esperados. Para registrar decisiones, se necesita contexto y justificación. Para reducir ambigüedad, se necesitan condiciones, límites, ejemplos y excepciones.

Un error común es aplicar el mismo nivel de detalle a todos los documentos. Esto produce guías demasiado generales, visiones generales demasiado largas o especificaciones incompletas. El objetivo ayuda a decidir cuánto detalle es suficiente.

4.12 Ejemplo: cancelar un turno

Tomemos la regla de cancelación de un turno. Si el objetivo es informar, el documento puede explicar que el sistema permite cancelar turnos bajo ciertas condiciones. Si el objetivo es guiar al usuario, debe indicar los pasos para ingresar al sistema, buscar el turno, seleccionar cancelar y confirmar la operación.

Si el objetivo es registrar una decisión, el documento puede explicar por qué se definió un límite de 24 horas y qué alternativas se evaluaron. Si el objetivo es reducir ambigüedad, debe especificar quién puede cancelar, hasta qué momento, qué ocurre con turnos ya atendidos, qué mensaje se muestra y qué eventos quedan registrados.

El tema es el mismo, pero la forma de documentarlo cambia según el objetivo.

4.13 Señales de que el objetivo no está claro

Existen señales que indican que un documento no tiene un objetivo claro:

• El título promete una cosa, pero el contenido desarrolla otra.
• El lector debe recorrer muchas secciones para encontrar una instrucción simple.
• Se mezclan explicaciones generales, pasos operativos y decisiones históricas sin separación.
• El documento incluye detalles que no ayudan a la tarea principal.
• Distintas personas interpretan de manera diferente lo que el documento pretende decir.
• No queda claro cuándo el documento está completo o actualizado.

4.14 Cómo declarar el objetivo de un documento

En documentos extensos conviene declarar explícitamente el objetivo. Puede hacerse en una sección inicial llamada "Propósito", "Objetivo" o "Alcance". Esa sección debe explicar para qué sirve el documento, a quién está dirigido y qué queda fuera.

Una declaración de objetivo no necesita ser larga. Lo importante es que oriente al lector y al autor. Por ejemplo: "Este documento describe los pasos necesarios para desplegar la aplicación en el ambiente de pruebas. Está dirigido al equipo de operación. No cubre instalación local ni cambios de infraestructura".

4.15 Errores frecuentes

Al definir objetivos de documentación suelen cometerse estos errores:

• Escribir sin saber qué acción o comprensión debe lograr el lector.
• Confundir una guía paso a paso con una explicación conceptual.
• Registrar decisiones sin explicar el contexto ni las alternativas.
• Usar frases generales que no reducen ambigüedad.
• Incluir detalles técnicos innecesarios para la audiencia principal.
• Crear documentos extensos sin secciones que separen objetivos distintos.
• No actualizar el objetivo cuando el documento cambia de uso.

4.16 Qué debes recordar de este tema

• Todo documento técnico debería tener un objetivo claro.
• Los objetivos más frecuentes son informar, guiar, registrar decisiones y reducir ambigüedad.
• Informar ayuda a comprender; guiar ayuda a realizar una tarea.
• Registrar decisiones conserva el razonamiento detrás de una elección.
• Reducir ambigüedad evita interpretaciones diferentes sobre reglas, contratos o procedimientos.
• El objetivo define estructura, lenguaje y nivel de detalle.
• Un documento puede combinar objetivos si los separa con claridad.

4.17 Conclusión

La documentación técnica es más útil cuando se escribe con un objetivo explícito. Saber si el documento busca informar, guiar, registrar decisiones o reducir ambigüedad permite seleccionar mejor el contenido y evitar mezclas confusas.

En el próximo tema estudiaremos los tipos de documentación que pueden aparecer en un proyecto de software y cómo elegir cuáles son necesarios según el contexto.