Qué problema estamos resolviendo

Un equipo puede recordar los encabezados, el texto alternativo y el contraste, pero olvidar que los ejemplos también son contenido. La página parece correcta, pero el fragmento más importante —código, respuesta JSON o tabla de referencia— resulta difícil de leer, depende demasiado del color o es incómodo para un lector de pantalla.

Una buena guía sobre ejemplos accesibles no solo da una recomendación general. Debe mostrar el patrón correcto dentro del propio artículo: contexto, resultado esperado, estructura visible y texto que conserve el sentido incluso sin colores.

Principios para ejemplos accesibles

  1. Explique el objetivo antes del bloque.
  2. No dependa del color como portador del significado.
  3. Separe éxito, advertencia y error.
  4. Use tablas solo para relaciones realmente tabulares.
  5. Mantenga un hecho por celda y un propósito por ejemplo.

Ejemplo 1. Explique la tarea y luego muestre la solicitud

Obtenga el informe 42. Sustituya <token> por un token válido. Si la solicitud tiene éxito, el servidor devuelve HTTP 200 y un JSON en el que status es ready.

GET /v1/reports/42 HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
{
  "id": 42,
  "status": "ready",
  "download_url": "/v1/reports/42/file"
}
{
  "error": "not_found",
  "message": "El informe 42 no existe o ya no está disponible."
}

Ejemplo 2. Los encabezados deben aportar significado

Campo Tipo Obligatorio Significado Nota
id integer sí Identificador del informe Aparece en todas las respuestas correctas
status string sí Estado del procesamiento Valores típicos: queued, running, ready, failed
download_url string no Enlace al archivo Solo aparece cuando status es ready
error string no Código de error Solo en respuestas fallidas
Revisión Pregunta Buena señal
Objetivo ¿Se entiende para qué sirve el ejemplo? El lector puede anticipar el resultado
Estructura ¿Éxito y error están separados? Hay bloques o etiquetas distintas
Tabla ¿Los encabezados definen el significado? La celda se entiende con su encabezado
Lenguaje ¿La explicación es clara y breve? El texto apoya al ejemplo en vez de ocultarlo

Ejemplo 3. Si importa la estructura, muestre el marcado

<table>
  <caption>Campos de la respuesta del informe</caption>
  <thead>
    <tr>
      <th scope="col">Campo</th>
      <th scope="col">Tipo</th>
      <th scope="col">Obligatorio</th>
      <th scope="col">Significado</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th scope="row"><code>status</code></th>
      <td>string</td>
      <td>sí</td>
      <td>Estado actual del procesamiento</td>
    </tr>
  </tbody>
</table>

Qué evitar

  • código sin contexto;
  • éxito o error expresados solo por color;
  • tablas usadas para pasos o párrafos;
  • celdas con varios hechos a la vez;
  • capturas de pantalla de código en lugar de texto copiable.

Patrón de trabajo para autores

  1. Objetivo.
  2. Requisito previo.
  3. Ejemplo.
  4. Resultado esperado.
  5. Caso de error.
  6. Tabla de referencia si hace falta.

Lista editorial breve

  • Explique el propósito antes del ejemplo.
  • Separe éxito y error.
  • Haga que el código sea comprensible sin color.
  • Use tablas solo cuando filas y columnas expresen una relación real.
  • Prefiera texto copiable a imágenes de código.

Materiales relacionados