31. Revisión, validación y pruebas de la documentación técnica
31.1 Introducción
La documentación técnica también necesita control de calidad. Un documento puede estar bien escrito en apariencia, pero contener instrucciones que no funcionan, enlaces rotos, ejemplos incorrectos, reglas ambiguas o información desactualizada.
Revisar, validar y probar documentación significa comprobar que cumple su objetivo: que es clara, correcta, completa, actualizada y útil para la audiencia prevista. No se trata solo de corregir ortografía; también se verifica el contenido técnico.
En este tema veremos tipos de revisión, validación con usuarios, pruebas de procedimientos, revisión de enlaces, ejemplos ejecutables, checklist y responsabilidades.
31.2 Por qué probar documentación
La documentación se usa para tomar decisiones y ejecutar acciones. Si una guía de instalación tiene un comando incorrecto, el lector queda bloqueado. Si una documentación de API muestra un ejemplo inválido, una integración puede fallar. Si una guía de operación omite un paso, un incidente puede prolongarse.
Probar documentación reduce estos riesgos. Permite detectar problemas antes de que afecten a usuarios, equipos de soporte, desarrollo u operación.
31.3 Calidad documental verificable
La imagen muestra un proceso de calidad documental: revisión técnica, revisión editorial, validación con audiencia, prueba de procedimientos, verificación de enlaces, ejemplos ejecutables y aprobación final.
31.4 Revisión técnica
La revisión técnica verifica que el contenido sea correcto desde el punto de vista del sistema. Debe comprobar que reglas, comandos, parámetros, diagramas, configuraciones, APIs y procedimientos coincidan con la realidad.
Quien revisa técnicamente debe conocer el área documentada. Por ejemplo, operación debería revisar procedimientos de despliegue, desarrollo debería revisar APIs y arquitectura, y análisis debería revisar reglas funcionales.
31.5 Revisión editorial
La revisión editorial verifica claridad, estilo, ortografía, acentuación, consistencia, títulos, estructura y facilidad de lectura. No reemplaza la revisión técnica, pero mejora la comprensión.
Puede detectar frases ambiguas, términos inconsistentes, secciones demasiado largas, títulos poco informativos o pasos mezclados con explicaciones.
31.6 Validación con la audiencia
Una documentación debe validarse con personas similares a quienes la usarán. Un desarrollador experto puede entender una guía que un nuevo integrante no puede seguir. Un analista puede aprobar una explicación funcional que un usuario final no entiende.
Validar con la audiencia permite detectar supuestos ocultos, términos desconocidos, requisitos previos omitidos y problemas de orden.
31.7 Prueba de procedimientos
Los procedimientos deben probarse ejecutándolos. Una guía de instalación se prueba desde un entorno limpio. Una guía de despliegue se prueba en un ambiente controlado. Un runbook se prueba simulando el incidente cuando sea posible.
Probar procedimientos permite detectar pasos faltantes, comandos incorrectos, permisos no mencionados, resultados esperados ausentes y condiciones no documentadas.
31.8 Verificación de ejemplos
Los ejemplos deben verificarse. Un ejemplo de API debe usar una solicitud válida. Un comando debe respetar sintaxis. Un fragmento de configuración debe tener formato correcto. Un escenario debe coincidir con reglas actuales.
Los ejemplos incorrectos son peligrosos porque muchas personas los copian y adaptan. Cuando un ejemplo falla, el lector puede pensar que el sistema falla o que la documentación no es confiable.
31.9 Enlaces y referencias
Los enlaces rotos reducen la utilidad de la documentación. También pueden indicar que se movieron documentos o que una referencia ya no existe. La revisión debe comprobar enlaces internos, archivos, imágenes, referencias cruzadas y recursos externos importantes.
En sitios grandes, esta verificación puede automatizarse parcialmente. Aun así, conviene revisar si el enlace apunta al contenido correcto, no solo si responde.
31.10 Consistencia entre documentos
La documentación relacionada debe ser consistente. Si un documento dice que la variable se llama DB_HOST y otro dice DATABASE_HOST, alguien tendrá problemas. Si una regla funcional cambia, pruebas, manuales y APIs relacionadas deben actualizarse.
La revisión debe considerar el ecosistema documental, no solo el archivo aislado.
31.11 Checklist de revisión
| Aspecto | Pregunta de revisión | Tipo de revisión |
|---|---|---|
| Exactitud | ¿Coincide con el sistema actual? | Técnica. |
| Claridad | ¿La audiencia puede entenderlo? | Editorial y audiencia. |
| Procedimiento | ¿Los pasos funcionan en orden? | Prueba práctica. |
| Referencias | ¿Los enlaces y recursos son correctos? | Automática y manual. |
| Completitud | ¿Faltan requisitos previos o resultados esperados? | Técnica y audiencia. |
31.12 Automatización de validaciones
Algunas validaciones pueden automatizarse: enlaces rotos, formato Markdown, generación del sitio, sintaxis de ejemplos, validación OpenAPI, ortografía básica o existencia de imágenes.
La automatización no reemplaza la revisión humana, pero ayuda a detectar errores repetitivos antes de publicar.
31.13 Criterios de aprobación
No todos los documentos requieren el mismo nivel de aprobación. Una guía interna simple puede necesitar revisión de un compañero. Una guía de producción puede requerir aprobación de operación. Una especificación funcional puede requerir validación de producto.
Definir criterios de aprobación evita publicar documentos críticos sin revisión suficiente.
31.14 Revisión continua
La revisión no ocurre solo antes de publicar. La documentación debe revisarse cuando cambia el sistema, cuando se detecta una duda frecuente, después de incidentes o durante ciclos periódicos de mantenimiento.
Una documentación que fue correcta hace seis meses puede no serlo hoy. Por eso, conviene registrar fecha de última revisión y responsable en documentos críticos.
31.15 Retroalimentación
La documentación mejora cuando quienes la usan pueden reportar problemas. Un enlace para comentarios, un canal de soporte interno o una tarea de mejora documental pueden ayudar a capturar dudas reales.
La retroalimentación de usuarios, soporte, desarrollo y operación muestra qué documentos son útiles, cuáles faltan y cuáles necesitan claridad.
31.16 Errores frecuentes
Al revisar documentación suelen aparecer estos errores:
- Revisar solo ortografía y no exactitud técnica.
- No probar procedimientos paso a paso.
- Aprobar documentación sin participación de la audiencia real.
- No verificar ejemplos ni comandos.
- Ignorar enlaces rotos o referencias desactualizadas.
- No revisar documentos relacionados cuando cambia una regla.
- No definir responsables de aprobación en documentos críticos.
31.17 Qué debes recordar de este tema
- La documentación técnica debe revisarse, validarse y probarse.
- La revisión técnica verifica exactitud del contenido.
- La revisión editorial mejora claridad, estructura y consistencia.
- La audiencia real ayuda a detectar supuestos ocultos.
- Los procedimientos deben ejecutarse siguiendo solo la guía.
- Los ejemplos, enlaces y referencias deben verificarse.
- La revisión documental debe continuar durante la vida del sistema.
31.18 Conclusión
Revisar y probar documentación técnica aumenta su confiabilidad. Una documentación validada reduce errores, mejora la experiencia del lector y fortalece el mantenimiento del sistema.
En el próximo tema estudiaremos publicación, búsqueda, navegación y accesibilidad de la documentación.