Redactar troballes i recomanacions que es corregeixen a la primera

A la lliçó anterior vas veure que cada troballa és una fitxa autònoma dins de l'informe, i al curs N4-C3 vas aprendre a registrar evidències mentre proves. Aquesta lliçó s'ocupa del que ve després: escriure. Una troballa ben redactada es corregeix a la primera; una de mal redactada genera tres rondes de preguntes, una correcció que només tapa el símptoma i una reauditoria en què torna a fallar.

La prova dels tres lectors

Abans de donar per tancada una troballa, imagina tres persones llegint-la sense poder-te preguntar res:

• Un desenvolupador que no era a l'auditoria ha de reproduir el problema seguint els teus passos i saber què ha de canviar al codi.
• Una responsable de producte o de continguts ha d'entendre a qui afecta, en quina tasca i per què té la severitat que té, per decidir quan s'arregla.
• Un altre auditor, sis mesos després, ha de verificar la correcció amb els mateixos passos i la mateixa combinació de navegador i tecnologia de suport.

Si algun dels tres necessités trucar-te, a la troballa li falta alguna cosa.

Títol i descripció: fets, no impressions

El títol es veurà a l'índex, al full de troballes i al gestor d'incidències del client. Una fórmula que funciona és on + què falla + conseqüència, quan la conseqüència cap en poques paraules:

• Malament: «Problema al formulari», «Error 4.1.2», «Botons no accessibles».
• Bé: «Els botons d'icona de la capçalera (cercar, menú, tancar la sessió) no tenen nom accessible».
• Bé: «L'error del camp DNI no s'associa al camp ni s'anuncia en enviar el formulari de cita prèvia».

La descripció té tres parts, sempre en el mateix ordre:

1. Què s'observa. Un fet comprovable, no una valoració. «NVDA anuncia "botó" sense cap nom en arribar a les tres icones de la capçalera» és un fet; «els botons no són accessibles» és una conclusió que el lector no pot verificar.
2. Per què incompleix. El criteri amb número i nom i, si existeix, l'error documentat de les WCAG que descriu la situació. Per exemple, F65 (imatges sense atribut alt ni alternativa textual) tanca qualsevol discussió sobre l'1.1.1 Contingut no textual.
3. A qui afecta i en quina tasca. «Qui fa servir un lector de pantalla no pot saber què fa cada botó ni, per tant, cercar al lloc o tancar la sessió en un ordinador compartit».

Evita «sembla que», «podria» o «és possible que». Si no estàs segur que alguna cosa falla, no és una troballa: és un resultat «no es pot determinar», amb el dubte explícit, com vas veure al curs N4-C1.

Passos per reproduir-la i evidències

Els passos s'escriuen com una recepta: numerats, un per acció, des d'una URL i un estat concrets, i acabant amb el resultat esperat i el resultat observat. Indica sempre la combinació de prova de la línia de base (sistema, navegador i tecnologia de suport amb la seva versió) i, si el problema en depèn, l'amplada de finestra o el nivell d'ampliació.

1. Obrir /tramites/cita-previa amb Firefox i NVDA a Windows (versions segons la línia de base de l'informe).
2. Escriure «1234» al camp DNI i prémer Retorn sobre «Enviar».
3. Esperat: el focus es desplaça al camp amb error o a un resum d'errors, i el lector anuncia l'error i com corregir-lo.
4. Observat: el focus continua a «Enviar» i no s'anuncia cap missatge.

Com a evidència, tria la que ho demostri amb menys soroll:

• Captura retallada al component, amb l'element assenyalat i un text alternatiu que digui què mostra («Camp DNI amb el missatge "Format incorrecte" en vermell, sense icona ni text addicional»).
• Fragment del DOM renderitzat, el que inspecciones a les eines del navegador, no el codi font de la plantilla, que pot no coincidir.
• Transcripció literal del que anuncia el lector, entre cometes, que val més que qualsevol descripció.
• Vídeo curt només si el problema és temporal (un focus que salta), amb descripció textual.

Infografia · Comparativa

Troballa vaga enfront de troballa accionable

El que separa una troballa que genera preguntes d'una que es corregeix i es verifica a la primera

Troballa vaga

• Títol genèric: «Problema al formulari»
• Valoració sense fets: «no és accessible»
• Sense passos ni combinació de prova
• Captura completa sense text alternatiu
• Recomanació copiada: «afegir ARIA»
• Sense criteri d'acceptació: ningú no sap quan està bé

Troballa accionable

• Títol amb on, què falla i conseqüència
• Fet observable, criteri i a qui afecta
• Passos numerats amb resultat esperat i observat
• Evidència mínima: retall, DOM o el que anuncia el lector
• Codi correcte i tècnica o patró de referència
• Criteri d'acceptació verificable amb teclat i lector

Llegir la infografia com a text

Comparativa en dues columnes. La columna de l'esquerra, «Troballa vaga», marcada com a incorrecta, enumera sis defectes: un títol genèric com «Problema al formulari»; una valoració sense fets, com «no és accessible»; l'absència de passos i de combinació de prova; una captura de pantalla completa sense text alternatiu; una recomanació copiada del tipus «afegir ARIA»; i la manca d'un criteri d'acceptació, de manera que ningú no sap quan està bé. La columna de la dreta, «Troballa accionable», marcada com a correcta, enumera els seus equivalents: títol amb on, què falla i conseqüència; un fet observable amb el seu criteri i a qui afecta; passos numerats amb resultat esperat i observat; l'evidència mínima, com un retall, el DOM o el que anuncia el lector; codi correcte amb la tècnica o el patró de referència; i un criteri d'acceptació verificable amb teclat i lector de pantalla.

La recomanació: resoldre el problema, no el símptoma

Sis regles fan útil una recomanació:

1. Comença pel resultat que cal aconseguir, abans que per la tècnica: «cada botó ha de tenir un nom accessible que en descrigui la funció: "Cercar", "Obrir el menú", "Tancar la sessió"».
2. Proposa la solució més senzilla i robusta. HTML natiu abans que ARIA, com diu la primera regla d'ús d'ARIA que vas veure al curs N3-C4.
3. Mostra codi incorrecte i correcte, mínim i provat.
4. Cita una referència: una tècnica suficient de les WCAG (per exemple, H44, que associa etiquetes a controls amb label) o el patró corresponent de l'APG (s'obre en una finestra nova) per a components complexos.
5. Indica on es corregeix: al component o a la plantilla, no pàgina a pàgina, i quantes instàncies es resolen amb aquest canvi.
6. Acaba amb un criteri d'acceptació que qualsevol pugui comprovar.

Per a la troballa H-14, la recomanació inclouria aquest codi:

<!-- Incorrecte: el missatge no està associat al camp -->
<label for="dni">DNI</label>
<input id="dni" name="dni">
<span class="rojo">Format incorrecte</span>

<!-- Correcte: estat d'error i missatge associat i explicatiu -->
<label for="dni">DNI</label>
<input id="dni" name="dni" aria-invalid="true" aria-describedby="dni-error">
<p id="dni-error">Error: el DNI ha de tenir 8 números i una lletra, per exemple 12345678Z.</p>

Es completaria així: en enviar amb errors, moure el focus al primer camp erroni o a un resum d'errors; criteri d'acceptació: «amb NVDA i VoiceOver, en enviar amb un DNI incomplet s'anuncia l'error i com corregir-lo, i en tornar al camp es llegeix el missatge».

To i estil

• Impersonal i factual. «El botó no té nom accessible», no «el desenvolupador va oblidar posar nom al botó». L'informe avalua un producte, no persones.
• Severitat justificada en una frase, lligada a la tasca: «alta, perquè impedeix saber que l'enviament ha fallat, tot i que la persona pot tornar-ho a intentar».
• Vocabulari constant. El mateix component es diu igual a tot l'informe («capçalera», no de vegades «header» i de vegades «barra superior»), i els termes tècnics són al glossari.
• Dos registres. Llenguatge clar a la descripció; llenguatge tècnic a la recomanació.

Troballes de continguts i de proveïdors externs

No totes les troballes les corregeix desenvolupament. Les que depenen de l'edició (text alternatiu, encapçalaments, enllaços, documents) necessiten una recomanació en forma de regla editorial amb exemple: «descriu la informació que aporta la imatge a la notícia; per a la foto del ple, "L'alcalde i els regidors voten l'ordenança de mobilitat", no "foto ple"». Si es repeteix en centenars de continguts, recomana a més un canvi al gestor que ho eviti, com un camp de text alternatiu obligatori amb l'opció explícita de marcar la imatge com a decorativa.

Quan el component és d'un proveïdor extern (un calendari de cita prèvia, una passarel·la de pagament, un reproductor), escriu la troballa de manera que el client la pugui reenviar tal qual: sense informació interna, amb l'evidència, el criteri, el comportament esperat i la referència a l'APG. Així rep una petició concreta i verificable.

Resum

• Una troballa està acabada quan un desenvolupador, una responsable de producte i un altre auditor la poden fer servir sense preguntar.
• Títol amb on, què falla i conseqüència; descripció amb el que s'observa, per què incompleix (criteri i error documentat) i a qui afecta.
• Passos numerats amb combinació de prova, resultat esperat i observat, i l'evidència mínima que ho demostri.
• La recomanació fixa el resultat, proposa la solució més senzilla amb codi, cita una tècnica o un patró, indica on es corregeix i acaba amb un criteri d'acceptació.
• To impersonal, vocabulari constant i troballes de continguts o de proveïdors redactades perquè es puguin traslladar tal qual.