Quel problème résolvons-nous ?

Une équipe pense aux titres, au texte alternatif et au contraste, mais oublie facilement que les exemples sont aussi du contenu. La page semble correcte, mais la partie la plus importante — exemple de code, réponse JSON ou tableau de référence — peut rester difficile à lire, trop dépendante de la couleur ou peu pratique pour un lecteur d’écran.

Un bon article ne doit pas seulement conseiller d’être prudent. Il doit montrer le bon modèle dans l’article lui-même : contexte, résultat attendu, structure visible et texte qui garde son sens même sans couleur.

Principes pour des exemples accessibles

  1. Annoncer l’objectif avant le bloc de code.
  2. Ne pas utiliser la couleur comme seul vecteur de sens.
  3. Séparer succès, avertissement et erreur.
  4. Utiliser un tableau uniquement pour une véritable relation tabulaire.
  5. Un fait par cellule et un objectif principal par exemple.

Exemple 1. Expliquer la tâche puis montrer la requête

Récupérez le rapport 42. Remplacez <token> par un jeton valide. En cas de succès, le serveur renvoie HTTP 200 et un JSON dont status vaut 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": "Le rapport 42 n’existe pas ou n’est plus disponible."
}

Exemple 2. Le sens doit être porté par les en-têtes

Champ Type Obligatoire Signification Note
id integer oui Identifiant du rapport Présent dans toutes les réponses réussies
status string oui État du traitement Valeurs typiques : queued, running, ready, failed
download_url string non Lien vers le fichier Présent seulement si status vaut ready
error string non Code d’erreur Présent uniquement en cas d’échec
Vérification Question Bon signe
Objectif Le but de l’exemple est-il clair ? Le lecteur peut anticiper le résultat
Structure Succès et erreur sont-ils séparés ? Blocs ou libellés distincts
Tableau Les en-têtes définissent-ils le sens ? La cellule est compréhensible avec son en-tête
Langage L’explication est-elle claire et concise ? Le texte aide l’exemple

Exemple 3. Quand la structure compte, montrer le balisage

<table>
  <caption>Champs de la réponse du rapport</caption>
  <thead>
    <tr>
      <th scope="col">Champ</th>
      <th scope="col">Type</th>
      <th scope="col">Obligatoire</th>
      <th scope="col">Signification</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th scope="row"><code>status</code></th>
      <td>string</td>
      <td>oui</td>
      <td>État actuel du traitement</td>
    </tr>
  </tbody>
</table>

Ce qu’il faut éviter

  • un bloc de code sans contexte ;
  • succès ou erreur indiqués seulement par la couleur ;
  • des tableaux utilisés pour des étapes ou de longs paragraphes ;
  • plusieurs faits indépendants dans une même cellule ;
  • des captures d’écran de code au lieu d’un texte copiable.

Modèle pratique pour les auteurs

  1. Objectif.
  2. Prérequis.
  3. Exemple.
  4. Résultat attendu.
  5. Erreur fréquente.
  6. Tableau de référence si nécessaire.

Liste éditoriale courte

  • Expliquer le but avant le bloc.
  • Séparer succès et erreur.
  • Rendre le code compréhensible sans couleur.
  • Utiliser un tableau uniquement pour de vraies relations ligne/colonne.
  • Préférer un texte copiable aux images de code.

Articles liés