Meilleure typographie pour des docs que les ingénieurs lisent vraiment

Pourquoi la typographie est un problème SRE

La documentation fait partie du plan de contrôle. Pas métaphoriquement — littéralement. Vos procédures d’incident, runbooks opérationnels, plans de migration et connaissances tribales « ce service est bizarre » y vivent. Si la typographie est hostile, le système devient hostile. Les ingénieurs feront toujours des changements, tourneront des clés, reconstruiront des arrays. Ils le feront juste de mémoire. C’est comme ça qu’apparaissent des procédures doucement différentes, des hypothèses divergentes et des incidents qui ne se reproduisent pas.

La typographie affecte trois métriques opérationnelles importantes :

• Temps pour obtenir une réponse sous contrainte. Une doc qui se parcourt en diagonal gagne. Une doc qui exige une lecture perd.
• Taux d’erreur lors du copier/coller. Code qui se casse, hyphénation ambiguë et glyphes semblables sont des sources fiables de commandes erronées.
• Sûreté des changements. Si les titres ne sont pas des ancres stables et que la longueur de ligne provoque des reflows chaotiques, les relecteurs manquent des diffs et la doc s’éloigne de la réalité.

La typographie ne réparera pas une topologie de stockage cassée. Mais elle empêchera le runbook de mentir par le formatage.

Une citation utile en ops : « L’espoir n’est pas une stratégie. » — Vince Lombardi. Ce n’est pas une citation de développeur, ce qui la rend d’autant plus utile. La mise en page de votre doc ne doit pas compter sur l’espoir que le lecteur « remarquera ».

Faits intéressants (parce que ça a une histoire)

• Les normes de longueur de ligne viennent des contraintes d’imprimerie. Journaux et livres ont convergé vers des mesures modérées parce que les lignes longues augmentent les erreurs de retour à la marge (perdre sa place).
• Les conventions de la machine à écrire ont façonné les attentes monospace. Les polices à chasse fixe ont entraîné des générations à lire des colonnes alignées — encore pertinent pour les logs, tableaux et sorties CLI.
• L’hyphénation était un travail manuel. Les compositeurs inséraient des traits d’union discrétionnaires à la main ; les algorithmes modernes le font automatiquement, parfois mal, surtout pour des termes techniques.
• ASCII explique pourquoi on se bat toujours contre les ressemblances. Le problème « 1/l/I » est ancien ; les enjeux ont changé quand ces caractères ont commencé à apparaître dans des secrets, jetons et noms d’hôte.
• Markdown a hérité d’habitudes de l’ère des emails. Beaucoup de conventions Markdown ont été optimisées pour la lisibilité en texte brut, pas pour un rendu soigné — d’où des interactions étranges avec le wrapping et les fences de code.
• Le support CSS de l’hyphénation est inégal. La propriété hyphens dépend des dictionnaires de langue et du comportement du navigateur ; ce n’est pas déterministe entre clients.
• Les ancres sont devenues des outils opérationnels. Une fois que la navigation dans la doc se fait via des fragments d’URL, le texte des titres commence à agir comme une API — le changer casse des runbooks et des tickets.
• Le choix de la police de code affecte la clarté des glyphes. Certaines polices rendent {}, [] et () trop similaires à petite taille — joli mais dangereux en production.

Blague #1 : La typographie, c’est comme le monitoring : si vous ne la remarquez que lorsqu’elle crie, vous êtes déjà en difficulté.

Longueur de ligne : le gouffre de temps silencieux

Si le texte de votre doc occupe toute la largeur d’un écran 34 pouces, vous avez créé un test d’endurance de lecture. Les lignes longues ne sont pas « plus d’information ». Ce sont plus de déplacements oculaires. Le déplacement oculaire coûte du temps. Sous pression, le temps devient des erreurs.

Que faire

• Ciblez 60–80 caractères par ligne pour le corps du texte. Si vous voulez un seul nombre : 72 est un bon défaut.
• Utilisez une largeur max mesurée en caractères (ch) plutôt qu’en pixels. Les pixels mentent selon les polices et les appareils ; les caractères se rapprochent de la réalité de lecture.
• Laissez le code être plus large que la prose mais n’autorisez pas le wrapping par défaut. Le défilement horizontal dans les blocs de code est moins mauvais que des commandes cassées qui changent de sens.

Modes de défaillance que vous verrez réellement

• Erreurs de retour à la marge : le lecteur perd sa place en passant de la fin d’une longue ligne au début de la suivante, surtout dans des paragraphes denses.
• Effondrement du scan : les titres deviennent moins efficaces parce que la page devient un mur ; la stratégie du lecteur devient « Ctrl+F et prier ».
• Bruit dans les diffs : si votre éditeur wrappe à une largeur et le site à une autre, de petites modifications réécrivent des paragraphes entiers, et les relecteurs cessent de faire confiance aux diffs.

CSS qui se comporte comme un adulte

C’est le genre de CSS que vous mettez sur un site de docs et que vous ne touchez plus à moins d’aimer les post-mortems.

cr0x@server:~$ cat docs-typography.css
:root{
  --measure: 72ch;
  --body-font: system-ui, -apple-system, "Segoe UI", Roboto, Arial, sans-serif;
  --mono-font: ui-monospace, SFMono-Regular, Menlo, Consolas, "Liberation Mono", monospace;
  --base-size: 16px;
  --line-height: 1.55;
}
main, article{
  max-width: var(--measure);
  margin: 0 auto;
  padding: 0 1rem;
  font-family: var(--body-font);
  font-size: var(--base-size);
  line-height: var(--line-height);
}
pre, code, kbd, samp{
  font-family: var(--mono-font);
}
pre{
  overflow-x: auto;
  white-space: pre;
  tab-size: 2;
}
code{
  font-size: 0.95em;
}

Ce fichier est un fichier, pas une promesse. La décision à prendre : mesurer la prose en caractères, la contraindre de façon centrale, et permettre aux blocs de code de défiler horizontalement plutôt que de se casser.

Ne pas être trop malin avec la typo fluide sans garde-fous

La typographie fluide peut être excellente. Elle peut aussi transformer silencieusement une mesure de 72ch en 110ch sur de larges écrans lorsqu’elle est combinée à une taille de police fluide. Si vous optez pour du fluide, plafonnez la mesure.

Des titres qui méritent leur place

Les titres ne sont pas de la décoration. Ce sont un système de navigation, un plan pour le survol et une API d’ancrage pour les liens issus de tickets, alertes et chats. Quand vous renommez des titres à la légère, vous cassez la mémoire musculaire des gens. Quand vous stylisez mal les titres, vous rendez la page difficile à parcourir.

Règles qui vous évitent des ennuis

• Une page, un H1. Faites-en la promesse de la page. Si le titre est vague, le reste ne sauvera pas la page.
• Les sections H2 doivent être compréhensibles hors contexte. « Configuration » n’est pas une section. « Configurer TLS pour les webhooks sortants » l’est.
• Gardez la hiérarchie des titres peu profonde. H2 et H3 font l’essentiel du travail. H4 sent le problème. H5 est un cri d’alarme.
• Ne stylisez pas les titres pour qu’ils ressemblent à des pubs. Un bon contraste et un poids raisonnable gagnent ; un texte géant en dégradé perd.
• Donnez des IDs stables aux titres. Si votre plateforme génère automatiquement des IDs à partir du texte, changer un mot casse les liens. Préférez des IDs explicites ou un mécanisme d’alias.

Choix typographiques qui influencent le comportement

Les ingénieurs parcourent en fonction de la forme. Si chaque titre a le même poids visuel que le texte, la page devient plate. Si chaque titre est énorme, la page devient bruyante. Vous voulez une échelle typographique claire : H2 est nettement différent, H3 est une sous-étape, et le texte garde son calme.

L’espacement compte plus que la police. La meilleure police de titre au monde ne compensera pas un rythme vertical serré. Donnez aux titres de l’air au-dessus, un espace plus serré en-dessous et gardez les listes proches du titre auquel elles appartiennent.

Les ancres comme interfaces opérationnelles

Si votre runbook dit « Aller à ‘Procédure de rollback rapide’ », cette expression doit exister et être linkable. Traitez les ancres de titres comme des points d’API : stables, versionnées si nécessaire, et non réécrites lors d’un « rafraîchissement de contenu ».

Polices de code et blocs : arrêter de casser les commandes

Les docs échouent le plus souvent dans le code. Les gens copient des commandes, les collent dans un shell root et appuient sur Entrée avec la même confiance qu’ils ont pour approuver une demande de changement. Votre travail est d’empêcher le texte de muter entre l’écran et le terminal.

Choisissez une police monospace pour la clarté, pas pour le style

Les polices monospace sont de l’infrastructure. Choisissez-en une avec :

• Des distinctions de glyphes claires : O vs 0, l vs 1, {} vs (), et un ; qui ne disparaît pas.
• Un bon hinting à petites tailles pour que le code ne devienne pas flou sur des écrans de faible qualité.
• Une largeur cohérente pour que tableaux et sorties alignées restent alignés.

Code en ligne vs blocs de code

• Le code en ligne sert pour des identifiants et courts extraits : chemins de fichiers, flags, clés JSON. Gardez-le court ; ne mettez pas de commandes complètes en inline.
• Les blocs de code servent pour tout ce que vous attendez qu’on copie/colle, tout ce qui est multi-ligne, et tout ce dont le wrapping change le sens.

Ne jamais wrapper les commandes par défaut

Le code qui se wrappe est une usine à commandes cassées sans erreur visible jusqu’à ce qu’il soit trop tard. C’est particulièrement vicieux avec :

• longs headers curl
• expressions JSONPath kubectl
• sorties CLI de stockage où les colonnes portent du sens
• tout ce qui contient des backslashes, des guillemets ou des heredocs

Rendre le copier/coller fiable

Utilisez white-space: pre et le défilement horizontal. Si vous souhaitez aider les utilisateurs mobiles, fournissez une version courte de la commande, pas un soft-wrapping. Assurez-vous aussi que votre site ne remplace pas les espaces normaux par des espaces insécables ou une « typographie intelligente » à l’intérieur des blocs de code. C’est ainsi qu’apparaissent des caractères Unicode invisibles qui cassent les shells.

Blague #2 : La seule chose pire qu’une commande cassée par un retour à la ligne est une commande cassée qui semble intacte.

Hyphénation : quand bonne mise en page rime avec mauvais copier/coller

L’hyphénation existe pour rendre le texte justifié moins hachuré. La plupart des docs techniques ne devraient pas utiliser de texte entièrement justifié. Si vous le faites, vous invitez des problèmes d’hyphénation, des rivières d’espace et une page qui ressemble à un traitement de texte mal configuré.

Quand l’hyphénation aide

Pour des colonnes étroites (mobile, barres latérales), l’hyphénation peut réduire des espacements maladroits et empêcher le texte aligné à droite de ressembler à quelque chose qui est tombé dans un escalier. Mais les docs techniques ne sont pas des romans. Ils contiennent des identifiants qui ne doivent pas être coupés : noms de fonctions, noms d’hôtes, flags et termes composés qui doivent rester recherchables.

Règles empiriques

• Désactivez l’hyphénation dans le code et les chaînes UI. Tout ce que le lecteur pourrait copier, taper ou rechercher ne doit pas être hyphéné.
• Activez l’hyphénation uniquement pour la prose et seulement si vous avez testé sur plusieurs navigateurs et si la langue du contenu est correctement définie.
• Évitez le texte justifié pour le corps. Le texte aligné à droite irrégulier est acceptable ; vos lecteurs sont des ingénieurs, pas des typographes.

Approche CSS qui ne sabote pas les tokens

cr0x@server:~$ cat hyphenation.css
article{
  hyphens: auto;
}
code, pre, kbd, samp, a, .no-hyphen{
  hyphens: none;
}
h1, h2, h3{
  hyphens: manual;
}

Décision : laissez le navigateur hyphénater les paragraphes (si vous le souhaitez vraiment), mais désactivez explicitement pour le code, les liens et tout ce qui ressemble à un token. Et : définissez correctement la langue du document. Les dictionnaires d’hyphénation en dépendent.

Les traits d’union invisibles sont un piège dans les docs techniques

Un trait d’union souple peut se glisser dans du texte copié et ruiner des correspondances — surtout dans des champs de recherche, des valeurs YAML et des chaînes shell. La plupart des navigateurs modernes n’incluent pas les traits d’union souples lors du copier, mais « la plupart » n’est pas un contrat. Si vous avez besoin de césures, utilisez le CSS. Gardez le texte source propre.

Mode d’emploi pour diagnostic rapide

Voici le playbook « ça paraît illisible ». Utilisez-le quand quelqu’un se plaint que la doc est difficile à lire, difficile à parcourir, ou « la commande que j’ai copiée n’a pas marché », et que vous devez trouver rapidement le goulot d’étranglement.

Premier point : vérifier la mesure et les retours à la ligne (les gains les plus importants)

1. La prose est-elle contrainte à ~60–80 caractères ? Si non, corrigez max-width (préférez ch).
2. Les blocs de code se cassent-ils ? Si oui, arrêtez cela. Utilisez le défilement horizontal et white-space: pre.
3. Les titres sont-ils visuellement distincts ? Si les titres ne ressortent pas, le scan échoue. Ajustez poids/taille/espacement.

Deuxième point : vérifier l’intégrité du copier/coller

1. Des « guillemets intelligents » ou substitutions typographiques sont-ils appliqués au code ? Ils casseront les shells et le JSON.
2. Y a-t-il des caractères invisibles ? NBSP, espaces à largeur zéro, traits d’union souples.
3. Les polices rendent-elles les glyphes ambigus ? Si O et 0 se ressemblent, secrets et IDs deviennent une roulette.

Troisième point : vérifier la navigation et les ancres

1. La table des matières reflète-t-elle la vraie structure ? Si elle est auto-générée mais que la hiérarchie est chaotique, elle n’aidera pas.
2. Les ancres de titres sont-elles stables ? Si les gens lient des sections depuis des tickets, changer les IDs casse le flux opérationnel.
3. Y a-t-il une recherche sur page qui fonctionne ? Si la recherche existe mais que la typographie rend les titres peu descriptifs, les résultats sont inutiles.

Douze+ tâches réelles avec commandes, sorties et décisions

Ce sont des vérifications pratiques que vous pouvez lancer sur un dépôt de docs ou un site rendu. Chaque tâche inclut : une commande, une sortie réaliste, ce que signifie la sortie et la décision à prendre. C’est la façon de transformer « la doc est mal foutue » en ticket exploitable.

Tâche 1 : Trouver les lignes suspectement longues en Markdown (prose)

cr0x@server:~$ python3 - <<'PY'
import os, re
root="docs"
limit=120
hits=0
for dp, _, files in os.walk(root):
  for f in files:
    if not f.endswith(".md"): 
      continue
    p=os.path.join(dp,f)
    with open(p,"r",encoding="utf-8") as fh:
      for i,line in enumerate(fh,1):
        if len(line.rstrip("\n"))>limit and not line.lstrip().startswith(("```","    ")):
          hits+=1
          print(f"{p}:{i}:{len(line.rstrip())}")
print("hits",hits)
PY
docs/runbooks/restore.md:44:168
docs/guide/architecture.md:112:203
hits 2

Sens : deux lignes de prose dépassent 120 caractères (pas dans des blocs de code). Cela indique souvent des paragraphes non reflowés ou du contenu collé qui rendra des lignes larges.

Décision : reflowez ces paragraphes dans la source (ou assurez-vous que le moteur de rendu wrappe). Si votre renderer traite les sauts de ligne Markdown comme des sauts durs, vous devez reflow.

Tâche 2 : Détecter des blocs de code cassés par le CSS

cr0x@server:~$ rg -n "white-space:\s*pre-wrap|white-space:\s*normal" site/assets/*.css
site/assets/main.css:418:white-space: pre-wrap;

Sens : les blocs de code peuvent utiliser pre-wrap qui wrappe les longues commandes.

Décision : changez pour white-space: pre pour les éléments pre, et autorisez le défilement horizontal.

Tâche 3 : Vérifier le CSS calculé pour un bloc de code (site rendu)

cr0x@server:~$ node - <<'NODE'
const fs=require('fs');
const html=fs.readFileSync('public/index.html','utf8');
console.log(html.includes('white-space: pre-wrap') ? 'pre-wrap found' : 'no pre-wrap in HTML');
NODE
no pre-wrap in HTML

Sens : le pre-wrap problématique provient probablement d’une feuille de style externe, pas du HTML inline.

Décision : corrigez le CSS à la source (design system/thème), pas dans des pages individuelles.

Tâche 4 : Trouver des guillemets typographiques dans des fences de code

cr0x@server:~$ python3 - <<'PY'
import re, pathlib
root=pathlib.Path("docs")
bad = ["\u2018","\u2019","\u201c","\u201d"]
for p in root.rglob("*.md"):
  t=p.read_text(encoding="utf-8",errors="ignore")
  in_code=False
  for i,line in enumerate(t.splitlines(),1):
    if line.strip().startswith("```"):
      in_code = not in_code
    if in_code and any(ch in line for ch in bad):
      print(f"{p}:{i}: smart quote in code fence")
PY
docs/runbooks/backup.md:87: smart quote in code fence

Sens : des guillemets courbes apparaissent dans un bloc de code, ce qui peut casser des shells et du JSON.

Décision : remplacez par des guillemets ASCII et empêchez l’éditeur/formatter de « smartener » les fences de code.

Tâche 5 : Attraper des espaces insécables dans des blocs de code (pièges du copier/coller)

cr0x@server:~$ python3 - <<'PY'
import pathlib
nbsp="\u00a0"
root=pathlib.Path("docs")
for p in root.rglob("*.md"):
  t=p.read_text(encoding="utf-8",errors="ignore")
  if nbsp in t:
    print(p, "contains NBSP")
PY
docs/guide/kubernetes.md contains NBSP

Sens : NBSP existe quelque part dans le Markdown. Dans le code, ça peut casser des flags et l’alignement de façon invisible.

Décision : remplacez NBSP par des espaces normaux ; ajoutez un lint pour prévenir la régression.

Tâche 6 : Auditer la hiérarchie des titres (trop profonde, étrange)

cr0x@server:~$ python3 - <<'PY'
import pathlib, re
root=pathlib.Path("docs")
for p in root.rglob("*.md"):
  levels=[]
  for line in p.read_text(encoding="utf-8",errors="ignore").splitlines():
    m=re.match(r'^(#{1,6})\s+', line)
    if m:
      levels.append(len(m.group(1)))
  if any(l>3 for l in levels):
    print(p, "has heading level > 3:", sorted(set(levels)))
PY
docs/guide/storage.md has heading level > 3: [1, 2, 3, 4, 5]

Sens : ce fichier utilise H4/H5 ; probablement un empilement de détails pour compenser une mauvaise structure.

Décision : restructurez en sections H2/H3 plus significatives. La profondeur est rarement synonyme de clarté.

Tâche 7 : Détecter des IDs d’ancre auto-générés instables (risque pour les runbooks)

cr0x@server:~$ rg -n "##\s+.*\s+\(deprecated\)|##\s+.*\s+\(old\)" docs/runbooks
docs/runbooks/restore.md:12:## Restore Procedure (old)

Sens : des titres sont renommés avec des qualificatifs comme « (old) », ce qui change probablement les slugs et casse les liens entrants.

Décision : gardez le titre stable et marquez le statut ailleurs (badge, note), ou ajoutez des IDs explicites si le système le permet.

Tâche 8 : Confirmer que le débordement des blocs de code est activé (préventif contre le wrapping)

cr0x@server:~$ rg -n "pre\s*\{|pre\." site/assets/main.css | head
212:pre{
218:  overflow-x: auto;
219:  white-space: pre;

Sens : le CSS utilise déjà le défilement horizontal et préserve les espaces.

Décision : bien — ne touchez pas. Si des utilisateurs signalent encore du wrapping, cherchez un CSS plus spécifique qui l’écrase.

Tâche 9 : Mesurer la longueur moyenne des lignes dans le HTML rendu (repérer les mises en page « full width »)

cr0x@server:~$ python3 - <<'PY'
from bs4 import BeautifulSoup
import pathlib, statistics, re
p=pathlib.Path("public/index.html")
soup=BeautifulSoup(p.read_text(encoding="utf-8",errors="ignore"),"html.parser")
text=" ".join(soup.get_text(" ").split())
chunks=re.findall(r'.{1,200}', text)
lens=[len(c) for c in chunks if len(c)>50]
print("sample chunk lengths:", lens[:8])
print("median:", int(statistics.median(lens)))
PY
sample chunk lengths: [200, 200, 200, 200, 200, 200, 200, 200]
median: 200

Sens : le texte extrait est découpé à 200 caractères, donc cet échantillon n’est pas une mesure parfaite — mais indique que la page a de longs segments de texte sans coupures naturelles.

Décision : utilisez ceci comme signal, pas comme preuve. Étape suivante : inspection visuelle et vérification du max-width du conteneur via le CSS.

Tâche 10 : Trouver les réglages d’hyphénation dans le CSS (et où ils s’appliquent)

cr0x@server:~$ rg -n "\bhyphens\s*:" site/assets/*.css
site/assets/main.css:88:  hyphens: auto;
site/assets/main.css:97:  hyphens: auto;

Sens : l’hyphénation est activée quelque part, possiblement de manière trop large.

Décision : vérifiez qu’elle est limitée aux conteneurs de prose ; désactivez pour le code, les liens et les spans de type token.

Tâche 11 : Détecter des traits d’union souples dans le contenu source

cr0x@server:~$ python3 - <<'PY'
import pathlib
shy="\u00ad"
root=pathlib.Path("docs")
count=0
for p in root.rglob("*.md"):
  t=p.read_text(encoding="utf-8",errors="ignore")
  if shy in t:
    n=t.count(shy)
    count+=n
    print(p, "soft hyphens:", n)
print("total",count)
PY
total 0

Sens : aucun trait d’union souple dans le Markdown. Bien — votre contenu n’est pas déjà contaminé.

Décision : conservez cet état en évitant le copier/coller depuis des sources qui injectent des traits d’union souples (certains PDF, certains éditeurs CMS).

Tâche 12 : Vérifier que la langue du document est définie (hyphénation et lecteurs d’écran)

cr0x@server:~$ python3 - <<'PY'
import pathlib, re
html=pathlib.Path("public/index.html").read_text(encoding="utf-8",errors="ignore")
m=re.search(r'<html[^>]*\blang="([^"]+)"', html)
print("lang=", m.group(1) if m else "missing")
PY
lang= en

Sens : la langue est définie. Cela affecte les dictionnaires d’hyphénation et les outils d’accessibilité.

Décision : assurez-vous que chaque page définit lang, pas seulement le template de la page d’accueil.

Tâche 13 : Trouver des blocs de code sans balise de langage (mauvaise pour la lisibilité et la sécurité du copier)

cr0x@server:~$ python3 - <<'PY'
import pathlib, re
root=pathlib.Path("docs")
for p in root.rglob("*.md"):
  lines=p.read_text(encoding="utf-8",errors="ignore").splitlines()
  for i,l in enumerate(lines,1):
    if l.strip()=="```":
      print(f"{p}:{i}: code fence without language")
      break
PY
docs/guide/ssl.md:55: code fence without language

Sens : des fences non étiquetées réduisent la qualité du highlight et parfois affectent les widgets de copie ou les règles de style.

Décision : étiquetez les fences (bash, json, yaml). La cohérence aide les lecteurs et les outils.

Tâche 14 : Vérifier la présence d’onglets dans des blocs de code (alignement variable selon l’environnement)

cr0x@server:~$ python3 - <<'PY'
import pathlib
root=pathlib.Path("docs")
in_code=False
for p in root.rglob("*.md"):
  in_code=False
  for i,line in enumerate(p.read_text(encoding="utf-8",errors="ignore").splitlines(),1):
    if line.strip().startswith("```"):
      in_code=not in_code
    if in_code and "\t" in line:
      print(f"{p}:{i}: tab in code fence")
      break
PY
docs/runbooks/network.md:102: tab in code fence

Sens : des tabs dans des fences de code peuvent rendre le rendu incohérent ; les sorties alignement-dépendantes ou le YAML sont particulièrement fragiles.

Décision : convertissez les tabs en espaces ; définissez tab-size en CSS si vous devez les garder (mais évitez-le).

Mini-histoires d’entreprise (parce que c’est comme ça que ça casse)

1) Incident causé par une mauvaise hypothèse : « Le site docs wrappe le code en toute sécurité »

L’entreprise avait un portail de docs interne propre. Thème agréable, bonne recherche, tout le pitch « developer experience ». Les runbooks étaient en Markdown, rendus via un générateur de site statique avec une couche CSS corporate par-dessus.

Pendant une rotation de certificat de routine, un ingénieur d’astreinte junior a suivi le runbook et copié une longue commande openssl avec plusieurs flags et chemins de fichiers. Le bloc de code avait l’air correct visuellement, parce que le thème soft-wrappait les lignes longues et insérait une indentation subtile au retour. Dans le terminal, la commande collée contenait un saut de ligne au milieu d’un flag. La commande a échoué, et l’ingénieur — sous léger stress — a fait le classique : l’a modifiée jusqu’à ce qu’elle tourne.

Elle a tourné. Elle a aussi généré une clé avec des paramètres différents de ceux prévus et l’a déposée dans un répertoire différent de celui attendu par le service. Le déploiement suivant a récupéré le mauvais fichier, et une partie des instances a commencé à échouer les handshakes TLS. L’incident n’a pas pris tout le service. Il a juste rendu une portion du trafic erratique, ce qui est pire parce que ça ressemble à un problème réseau.

Le postmortem n’était pas contre l’ingénieur. La mauvaise hypothèse était structurelle : « Si la commande est dans un bloc de code, elle est sûre à copier. » Ce n’était pas vrai. La correction a été ennuyeuse : désactiver le wrapping dans les blocs de code, ajouter un bouton de copie qui copie le texte brut et lint les runbooks pour les commandes longues sur une seule ligne. Ils ont aussi ajouté une section « Sortie attendue » dans le runbook pour que l’ingénieur puisse détecter la divergence plus tôt.

2) Optimisation qui a mal tourné : « On active la justification et l’hyphénation pour un look ‘livre’ »

Une initiative de redesign des docs a décidé que la plateforme interne ressemblait « trop à un wiki ». Quelqu’un a voulu un rendu plus poli. Ils ont activé le texte justifié pour créer des bords propres, puis activé l’hyphénation automatique pour réduire les grands espaces entre mots.

Sur desktop, la page d’accueil avait l’air… correcte. Sur mobile et en fenêtre divisée étroite (mode courant durant des incidents), la prose s’est hyphénée agressivement. Cela aurait été seulement ennuyeux si les règles d’hyphénation ne s’étaient pas déclenchées sur des termes techniques composés dans des titres et des tokens en ligne. Les lecteurs ont commencé à rechercher des termes vus sur la page et ne les retrouvaient pas parce qu’ils se souvenaient des fragments hyphénés.

Le problème majeur a frappé les runbooks : les intervenants parcourent les titres pour naviguer. Des titres hyphénés ont cassé ce schéma. Les gens ont cessé d’utiliser la TOC parce que les retours à la ligne faisaient paraître les titres comme des mots différents. Et comme l’équipe utilisait des ancres auto-générées, de petites éditions ont changé les IDs, brisant des liens depuis d’anciens tickets. « La doc ment » est devenu une plainte récurrente.

Le rollback a été simple mais politiquement douloureux : texte aligné à droite irrégulier, hyphénation désactivée par défaut, hyphénation autorisée seulement pour de longs paragraphes sur écrans étroits, et jamais dans les titres ni dans tout ce qui est marqué comme code. L’équipe de redesign a appris une vérité pratique : la typographie qui optimise l’esthétique peut réduire l’exactitude opérationnelle. Le but n’est pas « style livre ». Le but est « correct sous stress ».

3) Pratique ennuyeuse mais correcte qui a sauvé la mise : ancres stables et typographie conservatrice

Dans une autre entreprise, l’équipe docs avait une habitude qui semblait excessivement prudente : ils traitaient les titres et ancres comme des interfaces versionnées. Si un titre devait être renommé, ils gardaient l’ancien ancre comme alias, ou laissaient l’ancien titre comme cible d’ancrage cachée. Les ingénieurs plaisantaient en disant que la doc avait une « gouvernance API ». Ils n’avaient pas tort.

Puis un incident a frappé pendant une migration majeure de plateforme. La moitié de l’entreprise était en war room. Plusieurs équipes collaient des sections de runbook dans des threads : « allez à la section ‘Emergency failover’ », « utilisez la checklist ‘Disable writes’ », « vérifiez les étapes ‘Storage pool health’ ». Ces liens dataient de plusieurs mois, tirés d’anciens tickets et mémoire musculaire.

Ils ont tous fonctionné. Pas de 404, pas de « section introuvable », pas cinq minutes perdues par personne à chercher le titre renommé. La typographie du site était aussi conservative : mesure lisible, contraste fort pour les titres, blocs de code qui ne se cassaient pas et une mise en page prévisible où les blocs « Commande dangereuse » paraissaient dangereux.

Rien dans ce design n’a gagné de prix. Il a fait autre chose de plus précieux : il a réduit le coût de coordination pendant un outage. Les gens pouvaient faire confiance à la forme de la doc. Quand la forme de la doc est stable, les équipes dépensent leur budget de stress limité sur le système, pas sur la page.

Erreurs courantes : symptômes → cause racine → correction

Voici ce qui remonte typiquement via « la doc est nulle » dans les retours. Les symptômes sont réels. Les corrections ne sont généralement pas difficiles. Elles demandent juste que quelqu’un traite la doc comme de la production.

1) Symptom : « J’ai copié la commande et elle n’a pas marché »

Cause racine : les blocs de code se cassent, la typographie intelligente a changé des guillemets/tirets, ou des caractères invisibles existent (NBSP, espace zéro-largeur).

Correction : appliquer white-space: pre et overflow-x: auto ; désactiver les substitutions typographiques dans le code ; ajouter des règles de lint pour NBSP et guillemets intelligents dans les fences de code.

2) Symptom : « Cette page est épuisante à lire »

Cause racine : longueur de ligne trop grande ; interligne insuffisant ; faible contraste ; paragraphes denses sans structure.

Correction : contraindre la mesure à ~72ch ; définir un line-height ~1.5 ; augmenter légèrement l’espacement entre paragraphes ; fractionner les longues sections avec des titres H2/H3 significatifs.

3) Symptom : « La TOC est inutile »

Cause racine : titres génériques (« Overview », « Details ») ou hiérarchie trop profonde/erratique.

Correction : renommer les titres en énoncés orientés tâche ; garder la majorité du contenu en H2/H3 ; scinder ou séparer les pages qui nécessitent des H4/H5.

4) Symptom : « Les résultats de recherche n’aident pas »

Cause racine : les titres ne contiennent pas les mots recherchés par les utilisateurs ; termes critiques enterrés dans la prose ; hyphénation/coups de ligne affectent la mémoire des termes.

Correction : écrire des titres qui correspondent à l’intention utilisateur ; inclure les termes clés tôt ; éviter d’hyphéner les tokens ; s’assurer que la langue et l’indexation traitent correctement le code et les titres.

5) Symptom : « Les liens dans d’anciens tickets pointent au mauvais endroit »

Cause racine : les IDs auto-générés ont changé quand les titres ont été édités ; contenu réorganisé sans redirections/alias.

Correction : utiliser des IDs explicites et stables ; ajouter des alias d’ancre ; traiter les renommages comme des changements d’API avec support de migration.

6) Symptom : « Les tableaux et la sortie CLI ne s’alignent pas »

Cause racine : police de code pas vraiment monospace, ou police proportionnelle utilisée dans pre ; des tabs rendent le rendu incohérent.

Correction : définir une pile monospace fiable pour pre/code ; convertir les tabs en espaces ; définir explicitement tab-size.

7) Symptom : « Les titres ressemblent à des phrases en gras au hasard »

Cause racine : contraste typographique insuffisant ; espacement des titres trop serré ; poids trop léger ; style TOUT EN MAJ réduit la reconnaissance de forme.

Correction : augmenter la différence de taille/poids ; ajouter du rythme vertical ; éviter les MAJUSCULES pour les titres longs ; garantir la scannabilité des titres.

8) Symptom : « La mise en page mobile est chaotique »

Cause racine : les blocs de code tentent de rentrer à l’écran en se cassant ; mots longs débordent ; hyphénation sur les titres.

Correction : autoriser le défilement horizontal du code ; ajouter overflow-wrap: anywhere uniquement pour la prose ; garder l’hyphénation désactivée pour les titres et le code.

Checklists / plan étape par étape

Checklist : valeurs par défaut typographiques pour une plateforme de docs

• Conteneur de prose max-width : 65–75ch.
• Taille de corps : 16–18px selon la police ; line-height : 1.5–1.7.
• Texte aligné à gauche irrégulier ; éviter la justification complète.
• Échelle de titres : H2 clairement plus forte que le corps ; H3 distinct mais pas bruyant.
• Blocs de code : white-space: pre, overflow-x: auto, bouton de copie qui copie le texte brut.
• Police de code : une pile monospace claire ; éviter les ligatures fantaisie dans les docs opérationnels.
• Hyphénation : désactivée globalement sauf si testée ; si activée, limitée à la prose.
• Ancrages stables : IDs explicites ou stratégie d’alias ; traiter les renommages comme des breaking changes.
• Lint : détecter NBSP, guillemets intelligents dans le code, fences sans langage, tabs dans YAML/code.

Plan étape par étape : réparer un site de docs chaotique en une semaine

1. Jour 1 : mesure et wrapping. Ajoutez max-width: 72ch au conteneur principal. Empêchez le wrapping des blocs de code.
2. Jour 2 : titres et TOC. Normalisez la hiérarchie des titres. Scindez les pages qui nécessitent H4/H5 en pages ou sections séparées.
3. Jour 3 : intégrité du code. Désactivez la typographie intelligente dans le code. Ajoutez des checks de lint pour NBSP/guillemets intelligents. Ajoutez un bouton « copier brut » si la plateforme le permet.
4. Jour 4 : stabilité des ancres. Ne comptez plus sur les IDs auto-générés si possible. Ajoutez des alias pour les titres fréquemment linkés.
5. Jour 5 : décisions sur l’hyphénation. Soit désactivez l’hyphénation, soit limitez-la à la prose. Vérifiez que lang est défini et cohérent.
6. Jour 6 : accessibilité et contraste. Vérifiez le contraste des couleurs pour le texte et les titres. Rendez les styles de focus visibles pour la navigation au clavier.
7. Jour 7 : revue opérationnelle. Choisissez trois runbooks utilisés en incidents réels. Faites-les à sec : copier/coller les commandes, vérifier les sorties, vérifier que l’on peut atteindre la bonne section en 10 secondes.

Comment éviter les régressions

Les régressions typographiques sont sournoises parce que personne ne crée un ticket « line-height est passé de 1.55 à 1.3 ». Ils déposent « la doc est plus dure ». Prévenez cela avec de l’automatisation :

• Revue CSS : tout changement sur pre, code, tailles de titres et largeur du conteneur nécessite approbation.
• Lint de contenu en CI : rejeter NBSP et guillemets intelligents à l’intérieur des fences de code.
• Tests de régression visuelle sur une poignée de pages critiques (runbooks).

FAQ

1) Quelle est la meilleure longueur de ligne pour des docs techniques ?

Pour la prose, visez 60–80 caractères par ligne. Si vous devez choisir un défaut, utilisez 72ch sur le conteneur principal. C’est un bon compromis pour le scan et réduit la fatigue.

2) Les blocs de code doivent-ils se wrapper sur mobile ?

Non. Le wrapping change le sens et casse le copier/coller. Laissez les blocs de code défiler horizontalement. Si une commande est trop longue pour le mobile, fournissez une alternative courte ou un script.

3) L’hyphénation est-elle bonne ou mauvaise ?

Plutôt mauvaise dans les docs d’ingénierie. Elle peut aider pour des colonnes étroites en prose, mais elle doit être désactivée pour les titres, le code, les liens et les tokens. Si vous l’activez, isolez-la et testez.

4) Pourquoi pas justifier le texte ? Ça a l’air plus propre.

Le texte justifié produit souvent des espacements irréguliers (« rivières ») sur le web, surtout avec des colonnes étroites et des termes techniques. Le ragged-right est plus lisible et moins fragile.

5) Comment les titres affectent-ils la fiabilité ?

Les titres sont des API de navigation. Ils alimentent la TOC, la pertinence de la recherche et les liens entrants depuis des tickets. De mauvais titres ralentissent la réponse aux incidents. Des ancres instables cassent les workflows opérationnels.

6) Quelle police monospace devrions-nous utiliser ?

Choisissez une pile monospace système sauf si vous avez une raison forte de faire autrement. Optimisez pour la clarté des glyphes et le rendu à petites tailles. Évitez les polices où 0/O ou 1/l/I sont ambigus.

7) Faut-il utiliser les ligatures dans le code ?

Pour les docs opérationnels, je recommande non. Les ligatures rendent le code joli mais peuvent confondre les lecteurs et parfois affecter la sélection/copie. Réservez-les aux thèmes d’éditeur, pas aux runbooks.

8) Comment éviter des ancres cassées quand on change les titres ?

Utilisez des IDs explicites quand c’est possible. Si votre plateforme génère des ancres automatiquement, introduisez un mécanisme d’alias (ancres cachées) pour les sections souvent linkées. Traitez un renommage de titre comme un changement d’API.

9) Nos docs sont en Markdown. Faut-il hard-wrapper les lignes à 80 caractères ?

Ça dépend des outils. Le hard-wrap peut améliorer les diffs et la relecture, mais peut aussi créer des sauts bizarres si votre renderer traite les retours comme des sauts d’alinéa. Si vous hard-wrappez, assurez-vous que le processeur Markdown gère correctement le wrapping de paragraphes.

10) Quel est le changement à plus fort impact ?

Arrêter de wrapper les blocs de code et contraindre la mesure de la prose. Ces deux changements éliminent une quantité surprenante de friction opérationnelle.

Conclusion : actions concrètes

La typographie est une fonctionnalité de fiabilité. Elle détermine si la doc est utilisable quand le lecteur est fatigué, interrompu ou tente de ne pas aggraver la situation. Si vous voulez des docs que les ingénieurs lisent réellement, vous n’avez pas besoin d’un rebranding. Vous avez besoin de quelques valeurs par défaut obstinées et d’un peu d’automatisation.

Faites ceci ensuite

1. Réglez votre conteneur de contenu principal à ~72ch max et un interligne raisonnable.
2. Rendez les blocs de code non-wrap avec défilement horizontal. Ajoutez un bouton de copie si possible.
3. Désactivez l’hyphénation dans les titres, le code, les liens et les spans de type token. Envisagez de la désactiver partout.
4. Normalisez la hiérarchie des titres : H2 significatifs, H3 utiles, profondeur minimale.
5. Ajoutez des checks CI pour les guillemets intelligents, NBSP et fences sans langage.
6. Choisissez trois runbooks et testez-les comme s’il s’agissait d’un incident. Si c’est pénible au calme, ce sera dangereux à 3 h du matin.

Rendez la page ennuyeuse. Rendez-la cohérente. Rendez-la sûre à copier. C’est ainsi que la documentation gagne la confiance, et la confiance est la ressource la plus rare dans les systèmes en production.