Medidas de aseguramiento de calidad, tipos de documentación
Este artículo explica qué es la documentación como herramienta de QS, con preguntas de examen y etiquetas.
De un vistazo
La documentación hace verificables los requisitos, comportamientos y evidencias. Artefactos clave: documentación de usuario, documentación de interfaces, documentación de código, documentación de red, protocolos de prueba y listas de verificación — todos con objetivos claros, estructura, responsables y proceso de mantenimiento.
Descripción técnica compacta
Documentación de usuario
Dirigida a usuarios y operaciones: tareas, procedimientos paso a paso, escenarios de error, canales de soporte. Objetivo: autoservicio y menos carga en soporte.
Documentación de interfaces
Define contratos: endpoints, esquemas de datos, códigos de error, autenticación, versionamiento. Base para interoperabilidad y Contract Tests.
Documentación de código
Enfocada en implementación mantenible: descripción general de arquitectura, módulos, interfaces públicas, invariantes, comentarios en código, runbooks de construcción y ejecución.
Documentación de red
Describe topología, zonas, puertos, protocolos, flujos, controles de seguridad. Base para hardening y análisis de fallos.
Protocolos de prueba
Demuestran eficacia de pruebas: referencia a plan de pruebas, entorno, casos, resultados, defectos, aprobaciones.
Listas de verificación
Estandarizan inspecciones recurrentes (revisión de PRs, go-live, onboarding). Reducen omisiones.
Para la AP2 cuenta la conexión verificable: requisito → evidencia → resultado, enlazados a través de tickets, commits, builds y releases.
Puntos clave para examen
- Audiencia y propósito claros para cada documento
- Versionamiento, trazabilidad de cambios, responsables, ciclo de revisión
- Contenidos mínimos por tipo (usar plantillas de estructura)
- Función de evidencia (aceptación, auditoría, soporte, operaciones)
- Calidad: actual, completo, inequívoco, verificable, comprensible
- Vinculación con QS (requisito ↔ caso de prueba ↔ resultado ↔ defecto ↔ release)
- Herramientas: wikis, repositorios Markdown, diagramas como código, enlaces en tickets
- Relevancia IHK: demostrar que la documentación se mantiene, se versionan cambios, se enlazan referencias y está integrada en el proceso
Componentes clave
- Documentación de usuario (audiencia, tareas, pasos, ejemplos, ayuda para errores, soporte)
- Documentación de interfaces (propósito, endpoints, métodos, esquemas, errores, autenticación, versionamiento)
- Documentación de código (arquitectura, módulos, interfaces públicas, modelos de datos, invariantes, build/run)
- Documentación de red (topología, rangos IP, zonas, puertos/protocolos, reglas de firewall, flujos, HA)
- Protocolo de prueba (referencia a plan de pruebas, entorno, casos, resultados observados, defectos, aprobaciones)
- Lista de verificación (propósito, puntos de control, evidencias, responsables, fecha, resultado, desviaciones)
- Gobernanza (propietario, ciclo de revisión, registro de cambios, niveles de aprobación)
- Almacenamiento (fuente única, permisos de acceso, capacidad de búsqueda, versionamiento en repositorio)
- Calidad (lectura atenta, verificación de consistencia, seguimiento de actualización, verificación de enlaces)
- Cumplimiento (relación con ISO 25010, protección de datos, seguridad, operaciones)
Ejemplo práctico (API de carrito + portal de administración)
Documentación de usuario:
- Audiencia: empleados de procesamiento, administradores
- Tareas: registrar pedido, crear abono
- Secuencia de pasos: inicio → login → buscar cliente → añadir artículos → verificar descuento → finalizar pedido
- Ayuda para errores: mensajes de error comunes con soluciones
- Soporte: horarios de contacto, proceso de tickets
Documentación de interfaces:
- OpenAPI: POST /api/orders, GET /api/orders/{id}
- Esquemas: Order, LineItem (restricciones)
- Errores: 400 validación, 401 autenticación, 409 conflicto
- Autenticación: OAuth2, scopes order:write, order:read
- Versionamiento: Accept: application/vnd.shop.v1+json + plan de deprecación
Documentación de código:
- Arquitectura: capas, Controlador → Servicio → Repositorio, puertos y adaptadores
- Clases importantes: OrderService, invariante: monto total ≥ 0
- Configuración: perfiles, secretos a través de Vault
- Build: herramientas, comandos de inicio, logging, tracing
Documentación de red:
- Zonas: Internet → DMZ → App → DB
- Flujos: navegador → portal (TLS 443) → API (TLS 443) → DB (5432)
- Firewall: autorizaciones de principio, puntos de monitoreo
- HA: proxy inverso, 2 instancias, réplica de BD
Protocolo de prueba:
- Referencia a plan de pruebas: TP-007, entorno: Staging-23
- Casos: pedido con descuento, valores límite, rutas de error
- Resultado: aprobado, aprobado, fallido → ID de defecto 532
- Aprobación: product owner confirma, fecha, firma
Listas de verificación:
- Revisión de PR: arquitectura, seguridad, pruebas, documentación actualizada
- Go-live: monitoreo activo, runbooks completos, rollback disponible, feature flags preparados
Ventajas y desventajas
Ventajas
- Trazabilidad y capacidad de aceptación
- Incorporación más rápida
- Menores costos de operación y soporte
- Auditable
Desventajas
- Esfuerzo de mantenimiento
- Riesgo de contenidos obsoletos
- Requiere disciplina y propiedad clara
Preguntas de examen típicas (con respuesta breve)
- ¿Cuál es el propósito de la documentación de interfaces en QS? Define contratos verificables, permite Contract Tests, previene errores de integración.
- ¿Cuáles son los contenidos mínimos de la documentación de usuario? Audiencias, tareas, secuencias de pasos, ejemplos, ayuda para errores, canales de soporte, estado de versión.
- ¿Cómo ayuda la documentación de código a la mantenibilidad? Describe arquitectura, módulos, interfaces públicas, invariantes → reduce el esfuerzo de incorporación y cambios.
- ¿Qué debe contener un protocolo de prueba? Referencia a plan de pruebas, entorno, casos de prueba, resultados observados, defectos, aprobaciones, fecha, responsables.
- ¿Cuándo son útiles las listas de verificación? En tareas recurrentes con riesgo (revisión de PRs, go-live, onboarding).
Fuentes principales
- https://iso25000.com
- https://www.w3.org/TR/using-aria (para documentación semántica de UI)
- https://plantuml.com