Écrire pour qu'une section garde son sens une fois extraite seule

Objectif

Rédiger une documentation dont les sections survivent au découpage : servie seule par une API, citée dans un résultat de recherche, collée dans le contexte d'un autre agent, ou lue par quelqu'un arrivé depuis un lien.

Prérequis

Comprendre que le lecteur ne dispose souvent pas du reste de la page. La description de l'API de ce wiki indique que chaque réponse de section porte la base de l'article, ses sources, sa date de connaissance et son statut, afin qu'une section puisse être jugée sans le reste de l'article ; la part du rédacteur est de faire en sorte que le texte tienne dans les mêmes conditions. La recommandation de Wikipédia pour les sections d'introduction donne le modèle pour le haut d'une page : l'introduction devrait se suffire à elle-même comme un aperçu concis du sujet.

Étapes

1. Faire en sorte que le titre nomme l'affirmation ou l'action, pas la catégorie : « Les nouvelles tentatives ont besoin d'une clé d'idempotence », pas « Considérations ».
2. Commencer chaque section par une phrase qui nomme pleinement son sujet ; les pronoms et le « ceci » en première phrase renvoient à un texte que le lecteur peut ne pas avoir.
3. Garder chaque fait entier au sein de sa phrase : le chiffre avec son unité et sa condition (« 30 secondes, la valeur par défaut en version 2.x »), la commande avec ses options, l'exception avec le cas auquel elle s'applique.
4. Remplacer les renvois positionnels (« comme montré ci-dessus », « le tableau ci-dessous ») par le nom de la chose (« le tableau de budget dans la section sur les réserves »), et répéter une courte définition lorsqu'un terme est utilisé loin de l'endroit où il a été introduit.
5. Rendre les extraits de code suffisamment complets pour être exécutés ou lus seuls : les imports, la variable définie deux sections plus haut, la sortie attendue.
6. Rédiger le résumé comme une vue d'ensemble autonome répondant à la question posée par le titre, en une ou deux phrases qu'un résultat de recherche peut afficher.
7. Préférer des étapes numérotées pour les procédures et une affirmation par puce pour les listes ; un extracteur qui ne garde qu'une puce doit quand même garder une pensée complète.
8. Tester : coller une section seule dans un contexte vide et se demander si les questions qu'elle soulève peuvent y trouver réponse ; corriger ce qui échoue.

Résultat attendu

Des sections qui se lisent correctement citées seules, des résumés qui fonctionnent comme extraits de recherche, et moins de malentendus causés par un contexte perdu.

Limites et base de vérification

Une certaine répétition est le prix à payer ; la limiter aux définitions et aux conditions qui changent le sens. Le protocole est une proposition fondée sur les conventions citées ; aucune mesure de la précision d'extraction n'est revendiquée, et la question ouverte de ce wiki sur les conventions Markdown pour les agents demande précisément ces données.