L'alt text mancante è facile da trascurare in Markdown perché il sorgente può sembrare comunque completo. La sintassi immagine c'è, il path del file c'è e il documento può renderizzarsi con lo screenshot visibile. La parte mancante è il testo dentro le parentesi quadre.
I technical writer dovrebbero intercettarlo prima della pubblicazione. Il Validatore Markdown di Converty può far emergere alt text mancante insieme ad altri warning di authoring, così il problema è visibile mentre il sorgente è ancora facile da correggere.
Perché l'alt text mancante si nasconde in Markdown
La sintassi immagine Markdown appare così:
Quando la descrizione manca, l'immagine può comunque renderizzarsi:
Questo rende il problema facile da perdere durante una scansione visiva. La pagina può sembrare corretta all'autore, ma il sorgente ha perso contesto utile per chi dipende da alternative testuali e per i reviewer che cercano di capire il ruolo dell'immagine.
Controlla le immagini durante il passaggio di anteprima
Un workflow docs pratico dovrebbe includere un passaggio di review focalizzato sulle immagini:
- Incolla il Markdown nel Validatore Markdown.
- Controlla l'anteprima renderizzata per confermare che l'immagine appaia.
- Leggi la lista warning per l'alt text mancante.
- Torna al sorgente e scrivi una descrizione concisa che spieghi lo scopo dell'immagine.
- Ricontrolla il documento prima di pubblicare o committare.
È più veloce che aspettare che un reviewer trovi il problema in una pull request o in una pagina pubblicata.
Un buon alt text dipende dal contesto
L'alt text dovrebbe descrivere perché l'immagine conta nel documento. Uno screenshot di un validatore CSV non deve descrivere ogni pixel visibile. Può dover dire che il validatore mostra warning per header duplicati o un'anteprima parsata delle righe importate.
La descrizione migliore dipende dal testo circostante. Se il paragrafo spiega già completamente l'immagine, l'alt text può essere breve. Se l'immagine porta informazioni nuove, l'alt text dovrebbe aiutare a preservarle.
Abbina i controlli alt alla QA Markdown più ampia
L'alt text mancante è un problema di authoring tra diversi altri. Un buon passaggio di anteprima dovrebbe controllare anche struttura dei titoli, link, tabelle e code fence.
Per il workflow più ampio, leggi Come intercettare problemi Markdown prima della pubblicazione. Per la review tra team, usa Come i team prodotto e docs possono rivedere Markdown senza perdere formattazione.
Apri il Validatore Markdown prima di pubblicare Markdown quando screenshot o diagrammi fanno parte del documento.
