L'alt text absent és fàcil de passar per alt en Markdown perquè el source encara pot semblar complet. La sintaxi d'imatge hi és, el camí del fitxer hi és i el document pot renderitzar-se amb la captura visible. La part que falta és el text dins dels claudàtors.
Els technical writers haurien de detectar-ho abans de publicar. El validador Markdown de Converty pot mostrar alt text absent juntament amb altres avisos d'autoria, de manera que la incidència és visible mentre el source encara és fàcil de corregir.
Per què l'alt text absent s'amaga en Markdown
La sintaxi d'imatge Markdown és així:
Quan falta la descripció, la imatge encara pot renderitzar-se:
Això fa que la incidència sigui fàcil de perdre durant una revisió visual. La pàgina pot semblar correcta a l'autor, però el source ha perdut context útil per a lectors que depenen d'alternatives textuals i per a reviewers que intenten entendre el paper de la imatge.
Comprova imatges durant la passada de previsualització
Un workflow pràctic de docs hauria d'incloure un pas de review centrat en imatges:
- Enganxa el Markdown al validador Markdown.
- Revisa la vista prèvia renderitzada per confirmar que la imatge apareix.
- Llegeix la llista d'avisos per detectar alt text absent.
- Torna al source i escriu una descripció concisa que expliqui el propòsit de la imatge.
- Torna a comprovar el document abans de publicar o fer commit.
Això és més ràpid que esperar que un reviewer detecti la incidència en una pull request o en una pàgina publicada.
Un bon alt text depèn del context
L'alt text hauria de descriure per què la imatge importa en el document. Una captura d'un validador CSV no necessita descriure cada píxel visible. Pot necessitar dir que el validador mostra avisos de capçaleres duplicades o una vista prèvia parsejada de files importades.
La millor descripció depèn del text que l'envolta. Si el paràgraf ja explica completament la imatge, l'alt text pot ser breu. Si la imatge aporta informació nova, l'alt text ha d'ajudar a preservar aquesta informació.
Combina checks d'alt text amb QA Markdown més ampli
L'alt text absent és una incidència d'autoria entre diverses. Una bona passada de previsualització també hauria de comprovar estructura d'encapçalaments, enllaços, taules i blocs de codi.
Per al workflow més ampli, llegeix Com detectar problemes de Markdown abans de publicar. Per a review d'equip, fes servir Com els equips de producte i docs poden revisar Markdown sense perdre format.
Obre el validador Markdown abans de publicar Markdown quan captures o diagrames formen part del document.
