Redactar hallazgos y recomendaciones que se corrigen a la primera

En la lección anterior viste que cada hallazgo es una ficha autónoma dentro del informe, y en el curso N4-C3 aprendiste a registrar evidencias mientras pruebas. Esta lección se ocupa de lo que viene después: escribir. Un hallazgo bien redactado se corrige a la primera; uno mal redactado genera tres rondas de preguntas, una corrección que solo tapa el síntoma y una reauditoría en la que vuelve a fallar.

La prueba de los tres lectores

Antes de dar por cerrado un hallazgo, imagina a tres personas leyéndolo sin poder preguntarte nada:

• Un desarrollador que no estuvo en la auditoría tiene que reproducir el problema siguiendo tus pasos y saber qué cambiar en el código.
• Una responsable de producto o de contenidos tiene que entender a quién afecta, en qué tarea y por qué tiene la severidad que tiene, para decidir cuándo se arregla.
• Otro auditor, seis meses después, tiene que verificar la corrección con los mismos pasos y la misma combinación de navegador y tecnología de apoyo.

Si alguno de los tres necesitaría llamarte, al hallazgo le falta algo.

Título y descripción: hechos, no impresiones

El título se verá en el índice, en la hoja de hallazgos y en el gestor de incidencias del cliente. Una fórmula que funciona es dónde + qué falla + consecuencia, cuando la consecuencia cabe en pocas palabras:

• Mal: «Problema en formulario», «Fallo 4.1.2», «Botones no accesibles».
• Bien: «Los botones de icono de la cabecera (buscar, menú, cerrar sesión) no tienen nombre accesible».
• Bien: «El error del campo DNI no se asocia al campo ni se anuncia al enviar el formulario de cita previa».

La descripción tiene tres partes, siempre en el mismo orden:

1. Qué se observa. Un hecho comprobable, no una valoración. «NVDA anuncia "botón" sin ningún nombre al llegar a los tres iconos de la cabecera» es un hecho; «los botones no son accesibles» es una conclusión que el lector no puede verificar.
2. Por qué incumple. El criterio con número y nombre y, si existe, el fallo documentado de las WCAG que describe la situación. Por ejemplo, F65 (imágenes sin atributo alt ni alternativa textual) cierra cualquier discusión sobre 1.1.1 Contenido no textual.
3. A quién afecta y en qué tarea. «Quien usa un lector de pantalla no puede saber qué hace cada botón ni, por tanto, buscar en el sitio o cerrar su sesión en un equipo compartido».

Evita «parece que», «podría» o «es posible que». Si no estás seguro de que algo falla, no es un hallazgo: es un resultado «no se puede determinar», con la duda explícita, como viste en el curso N4-C1.

Pasos para reproducir y evidencias

Los pasos se escriben como una receta: numerados, uno por acción, desde una URL y un estado concretos, y terminando con el resultado esperado y el resultado observado. Indica siempre la combinación de prueba de la línea base (sistema, navegador y tecnología de apoyo con su versión) y, si el problema depende de ello, el ancho de ventana o el nivel de ampliación.

1. Abrir /tramites/cita-previa con Firefox y NVDA en Windows (versiones según la línea base del informe).
2. Escribir «1234» en el campo DNI y pulsar Intro sobre «Enviar».
3. Esperado: el foco se desplaza al campo con error o a un resumen de errores, y el lector anuncia el error y cómo corregirlo.
4. Observado: el foco sigue en «Enviar» y no se anuncia ningún mensaje.

Como evidencia, elige la que lo demuestre con menos ruido:

• Captura recortada al componente, con el elemento señalado y un texto alternativo que diga qué muestra («Campo DNI con el mensaje "Formato incorrecto" en rojo, sin icono ni texto adicional»).
• Fragmento del DOM renderizado, el que inspeccionas en las herramientas del navegador, no el código fuente de la plantilla, que puede no coincidir.
• Transcripción literal de lo que anuncia el lector, entre comillas, que vale más que cualquier descripción.
• Vídeo corto solo si el problema es temporal (un foco que salta), con descripción textual.

Infografía · Comparativa

Hallazgo vago frente a hallazgo accionable

Lo que separa un hallazgo que genera preguntas de uno que se corrige y se verifica a la primera

Hallazgo vago

• Título genérico: «Problema en formulario»
• Valoración sin hechos: «no es accesible»
• Sin pasos ni combinación de prueba
• Captura completa sin texto alternativo
• Recomendación copiada: «añadir ARIA»
• Sin criterio de aceptación: nadie sabe cuándo está bien

Hallazgo accionable

• Título con dónde, qué falla y consecuencia
• Hecho observable, criterio y a quién afecta
• Pasos numerados con resultado esperado y observado
• Evidencia mínima: recorte, DOM o lo que anuncia el lector
• Código correcto y técnica o patrón de referencia
• Criterio de aceptación verificable con teclado y lector

Leer la infografía como texto

Comparativa en dos columnas. La columna de la izquierda, «Hallazgo vago», marcada como incorrecta, enumera seis defectos: un título genérico como «Problema en formulario»; una valoración sin hechos, como «no es accesible»; la ausencia de pasos y de combinación de prueba; una captura de pantalla completa sin texto alternativo; una recomendación copiada del tipo «añadir ARIA»; y la falta de un criterio de aceptación, de modo que nadie sabe cuándo está bien. La columna de la derecha, «Hallazgo accionable», marcada como correcta, enumera sus equivalentes: título con dónde, qué falla y consecuencia; un hecho observable con su criterio y a quién afecta; pasos numerados con resultado esperado y observado; la evidencia mínima, como un recorte, el DOM o lo que anuncia el lector; código correcto con la técnica o el patrón de referencia; y un criterio de aceptación verificable con teclado y lector de pantalla.

La recomendación: resolver el problema, no el síntoma

Seis reglas hacen útil una recomendación:

1. Empieza por el resultado que hay que conseguir, antes que por la técnica: «cada botón debe tener un nombre accesible que describa su función: "Buscar", "Abrir menú", "Cerrar sesión"».
2. Propón la solución más sencilla y robusta. HTML nativo antes que ARIA, como dice la primera regla de uso de ARIA que viste en el curso N3-C4.
3. Muestra código incorrecto y correcto, mínimo y probado.
4. Cita una referencia: una técnica suficiente de las WCAG (por ejemplo, H44, que asocia etiquetas a controles con label) o el patrón correspondiente de la APG (se abre en una ventana nueva) para componentes complejos.
5. Indica dónde se corrige: en el componente o la plantilla, no página a página, y cuántas instancias se resuelven con ese cambio.
6. Termina con un criterio de aceptación que cualquiera pueda comprobar.

Para el hallazgo H-14, la recomendación incluiría este código:

<!-- Incorrecto: el mensaje no está asociado al campo -->
<label for="dni">DNI</label>
<input id="dni" name="dni">
<span class="rojo">Formato incorrecto</span>

<!-- Correcto: estado de error y mensaje asociado y explicativo -->
<label for="dni">DNI</label>
<input id="dni" name="dni" aria-invalid="true" aria-describedby="dni-error">
<p id="dni-error">Error: el DNI debe tener 8 números y una letra, por ejemplo 12345678Z.</p>

Se completaría así: al enviar con errores, mover el foco al primer campo erróneo o a un resumen de errores; criterio de aceptación: «con NVDA y VoiceOver, al enviar con un DNI incompleto se anuncia el error y cómo corregirlo, y al volver al campo se lee el mensaje».

Tono y estilo

• Impersonal y factual. «El botón no tiene nombre accesible», no «el desarrollador olvidó poner nombre al botón». El informe evalúa un producto, no a personas.
• Severidad justificada en una frase, ligada a la tarea: «alta, porque impide saber que el envío ha fallado, aunque la persona puede intentarlo de nuevo».
• Vocabulario constante. El mismo componente se llama igual en todo el informe («cabecera», no a veces «header» y a veces «barra superior»), y los términos técnicos están en el glosario.
• Dos registros. Lenguaje claro en la descripción; lenguaje técnico en la recomendación.

Hallazgos de contenidos y de proveedores externos

No todos los hallazgos los corrige desarrollo. Los que dependen de la edición (texto alternativo, encabezados, enlaces, documentos) necesitan una recomendación en forma de regla editorial con ejemplo: «describe la información que aporta la imagen en la noticia; para la foto del pleno, "El alcalde y los concejales votan la ordenanza de movilidad", no "foto pleno"». Si se repite en cientos de contenidos, recomienda además un cambio en el gestor que lo evite, como un campo de texto alternativo obligatorio con la opción explícita de marcar la imagen como decorativa.

Cuando el componente es de un proveedor externo (un calendario de cita previa, una pasarela de pago, un reproductor), escribe el hallazgo de forma que el cliente pueda reenviarlo tal cual: sin información interna, con la evidencia, el criterio, el comportamiento esperado y la referencia a la APG. Así recibe una petición concreta y verificable.

Resumen

• Un hallazgo está terminado cuando un desarrollador, una responsable de producto y otro auditor pueden usarlo sin preguntar.
• Título con dónde, qué falla y consecuencia; descripción con lo que se observa, por qué incumple (criterio y fallo documentado) y a quién afecta.
• Pasos numerados con combinación de prueba, resultado esperado y observado, y la evidencia mínima que lo demuestre.
• La recomendación fija el resultado, propone la solución más sencilla con código, cita una técnica o patrón, indica dónde se corrige y termina con un criterio de aceptación.
• Tono impersonal, vocabulario constante y hallazgos de contenidos o de proveedores redactados para que se puedan trasladar tal cual.