7. Planificación documental: alcance, responsables, entregables y calendario

7.1 Introducción

La documentación técnica no debería depender de la improvisación. Si se escribe solo cuando alguien tiene tiempo, suele quedar incompleta, desactualizada o dispersa. Para que sea útil, conviene planificar qué se documentará, quién lo hará, cuándo se entregará y cómo se mantendrá.

La planificación documental consiste en organizar el trabajo de documentación dentro del proyecto. No significa crear burocracia innecesaria, sino definir un marco claro para que la documentación acompañe el desarrollo del software y no aparezca tarde, desconectada o sin responsables.

En este tema veremos cómo definir alcance, responsables, entregables, calendario, prioridades, revisiones y criterios de actualización.

7.2 Por qué planificar la documentación

Planificar la documentación ayuda a evitar dos extremos: documentar demasiado sin utilidad o documentar tan poco que el equipo queda sin información crítica. Una planificación adecuada permite concentrar esfuerzo en los documentos que realmente reducen riesgo, mejoran la comunicación o facilitan el mantenimiento.

Además, la planificación permite asignar tiempo. Es frecuente que la documentación se pida al final, cuando ya no queda margen para escribir, revisar y validar. Si se incluye desde el inicio, puede evolucionar junto con requisitos, diseño, código, pruebas y operación.

7.3 Elementos de la planificación documental

La imagen representa los elementos principales de una planificación documental: alcance, audiencias, responsables, entregables, calendario, revisiones y mantenimiento. Todos estos elementos ayudan a convertir la documentación en una actividad gestionada y no en una tarea informal.

7.4 Definir el alcance documental

El alcance documental indica qué temas se documentarán y qué temas quedarán fuera. Esta definición es importante porque ningún proyecto puede documentar todo con el mismo nivel de detalle. El alcance debe responder a las necesidades reales del producto, del equipo y de las audiencias.

Para definirlo conviene identificar funcionalidades críticas, reglas de negocio complejas, integraciones externas, decisiones de arquitectura, procedimientos de instalación, operación, seguridad y partes del sistema que probablemente cambien o requieran mantenimiento.

También es necesario indicar lo que no se incluirá. Por ejemplo, una guía de despliegue puede excluir instalación local de desarrollo. Un manual de usuario puede excluir configuración interna del servidor. Esta separación evita documentos interminables.

7.5 Identificar audiencias

La planificación debe indicar para quién se escribirá cada documento. Un mismo proyecto puede necesitar documentación para usuarios finales, desarrolladores, testers, operación, soporte, gestión y nuevos integrantes del equipo.

Definir la audiencia permite ajustar el lenguaje, el nivel de detalle y el formato. Una guía para soporte necesita síntomas, causas y acciones. Una guía para desarrolladores necesita instalación local, estructura, pruebas y convenciones. Una guía de usuario necesita pasos orientados a tareas y explicaciones sin detalles internos innecesarios.

7.6 Definir responsables

Todo documento importante debería tener responsables. Esto no significa que una sola persona escriba todo, sino que alguien debe coordinar, revisar o mantener cada contenido. Sin responsables, los documentos suelen quedar abandonados después de la primera versión.

Los responsables pueden variar según el tipo de documento. Un analista puede liderar documentación funcional. Un arquitecto o líder técnico puede revisar decisiones de arquitectura. Un desarrollador puede mantener documentación de API. Operación puede validar procedimientos de despliegue y monitoreo. Soporte puede contribuir con problemas frecuentes.

7.7 Definir entregables

Los entregables documentales son los documentos o piezas de información que se producirán. Pueden ser archivos Markdown, páginas HTML, secciones de una wiki, documentos formales, diagramas, manuales, guías, registros de decisiones o referencias de API.

Un entregable debe tener nombre, objetivo, audiencia, ubicación y criterio de finalización. No alcanza con decir "hacer documentación técnica". Es mejor definir, por ejemplo, "guía de instalación local para desarrolladores", "referencia de API de turnos" o "procedimiento de despliegue en producción".

7.8 Definir calendario

El calendario documental indica cuándo se creará, revisará y actualizará cada documento. La documentación debe estar disponible en el momento en que se necesita. Una guía de instalación debe existir antes de incorporar nuevos desarrolladores. Una documentación de API debe estar lista antes de que otros sistemas la integren. Un procedimiento de operación debe existir antes de pasar a producción.

En proyectos ágiles, la documentación puede planificarse dentro de iteraciones. En proyectos más formales, puede formar parte de hitos o entregas. Lo importante es que no quede separada del trabajo técnico que documenta.

7.9 Priorizar documentación

Cuando el tiempo es limitado, conviene priorizar la documentación que reduce más riesgo. No todos los documentos tienen la misma urgencia. Una regla crítica, un procedimiento de despliegue o una integración externa suelen necesitar documentación antes que detalles menores de una pantalla simple.

Una forma práctica de priorizar es evaluar impacto y frecuencia. Si un documento se usará muchas veces o evita errores costosos, debe tener prioridad. Si una parte del sistema cambia mucho, quizá conviene documentar el criterio y los contratos estables, no cada detalle transitorio.

7.10 Ubicación y formato

La planificación también debe definir dónde vivirá la documentación y en qué formato. Puede estar en el mismo repositorio que el código, en una wiki, en un sitio estático, en una herramienta de gestión del conocimiento o en documentos compartidos.

La elección depende del uso. La documentación que cambia junto con el código suele funcionar bien en el repositorio. La ayuda para usuarios puede publicarse en un sitio accesible. Los procedimientos internos pueden vivir en una wiki con control de permisos. Lo importante es que la ubicación sea conocida y que el formato facilite mantenimiento.

7.11 Revisión y aprobación

La documentación técnica debe revisarse. Una revisión puede detectar errores, ambigüedades, omisiones, ejemplos que no funcionan o diferencias con el sistema real. La revisión puede ser técnica, funcional, editorial o de audiencia.

No todos los documentos requieren la misma formalidad. Un README puede revisarse en una solicitud de cambio. Un procedimiento de producción puede necesitar validación de operación. Una especificación funcional puede requerir aprobación del responsable del producto. La planificación debe indicar qué nivel de revisión corresponde.

7.12 Mantenimiento documental

La documentación no termina cuando se publica. Debe mantenerse mientras el sistema cambia. Por eso, la planificación debe definir cómo se detectarán documentos afectados por cambios y quién los actualizará.

Una práctica útil es incluir la documentación en la definición de terminado de una tarea. Si una funcionalidad cambia una API, una regla o un procedimiento, la tarea no debería considerarse completa hasta revisar la documentación relacionada.

7.13 Trazabilidad documental

La trazabilidad permite relacionar documentos entre sí y con otros artefactos del proyecto. Por ejemplo, un requisito puede vincularse con una regla funcional, un endpoint de API, un caso de prueba y una decisión técnica.

No siempre se necesita una matriz formal de trazabilidad, pero sí conviene mantener enlaces o referencias claras. Esto ayuda a evaluar impactos cuando cambia una regla, se corrige un error o se modifica una integración.

7.14 Plan documental mínimo

Un plan documental no tiene por qué ser extenso. Para un proyecto pequeño puede bastar una tabla con documentos previstos, audiencia, responsable, ubicación, estado y fecha de revisión. Lo importante es que exista una visión común del trabajo documental.

7.15 Ejemplo: planificación para sistema de turnos

En un sistema de gestión de turnos, el plan documental podría incluir una documentación funcional de reserva y cancelación, un glosario de conceptos del dominio, una referencia de API para integraciones, una guía de instalación local, un procedimiento de despliegue, una guía de soporte para problemas frecuentes y un manual de usuario.

El equipo de análisis podría mantener reglas de negocio. Desarrollo podría mantener API y ejecución local. Operación podría validar despliegue y respaldos. Soporte podría registrar consultas frecuentes. De esta forma, la documentación queda distribuida según el conocimiento de cada rol, pero coordinada por una planificación común.

7.16 Errores frecuentes

Al planificar documentación suelen aparecer estos errores:

• No definir audiencia ni objetivo para cada entregable.
• Crear una lista de documentos demasiado ambiciosa para el tiempo disponible.
• No asignar responsables de mantenimiento.
• Dejar la documentación para el final del proyecto.
• No revisar los documentos con personas de la audiencia real.
• Ubicar documentación en lugares que el equipo no consulta.
• No relacionar cambios de software con cambios de documentación.

7.17 Qué debes recordar de este tema

• La planificación documental organiza qué se documentará, quién lo hará y cuándo se entregará.
• El alcance documental define qué temas se incluyen y cuáles quedan fuera.
• Cada documento debe tener audiencia, objetivo, responsable y ubicación.
• La documentación debe planificarse junto con el trabajo técnico.
• Conviene priorizar documentos que reducen riesgo o se usan con frecuencia.
• La revisión y el mantenimiento deben formar parte del plan.
• Un plan documental puede ser simple, pero debe ser explícito y útil.

7.18 Conclusión

Planificar la documentación técnica permite producir contenido útil en el momento adecuado. Al definir alcance, responsables, entregables y calendario, el equipo evita improvisaciones y reduce el riesgo de documentos incompletos o desactualizados.

En el próximo tema estudiaremos la estructura de documentos técnicos: títulos, secciones, navegación y referencias.