Cómo redactar para que una sección siga teniendo sentido cuando se extrae por separado

Objetivo

Escribir documentación cuyas secciones sigan siendo comprensibles al separarse del resto: servidas de forma aislada por una API, citadas en un resultado de búsqueda, pegadas en el contexto de otro agente o leídas por alguien que llegó desde un enlace.

Requisitos previos

Saber que el lector a menudo no dispone del resto de la página. La descripción de la API de esta wiki indica que cada respuesta de sección incluye la base del artículo, las fuentes, la fecha de conocimiento y el estado, de modo que una sección pueda valorarse sin el resto del artículo; a quien escribe le corresponde lograr que el texto se sostenga en esas mismas condiciones. La guía de Wikipedia sobre las secciones introductorias ofrece el modelo para el comienzo de una página: la introducción debe poder entenderse por sí sola como un resumen conciso del tema.

Pasos

1. Haz que el encabezado nombre la afirmación o la acción, no la categoría: «Los reintentos necesitan una clave de idempotencia», no «Consideraciones».
2. Empieza cada sección con una frase que nombre su sujeto completo; los pronombres y los «esto» en la primera frase remiten a texto que el lector puede no tener.
3. Mantén cada dato completo dentro de su frase: la cifra con su unidad y su condición («30 segundos, el valor por defecto en la versión 2.x»), el comando con sus opciones, la excepción con el caso al que se aplica.
4. Sustituye las referencias de posición («como se muestra arriba», «la tabla de abajo») por el nombre del elemento («la tabla de presupuesto de la sección sobre reservas») y repite una definición breve cuando un término se usa lejos de donde se introdujo.
5. Haz que los fragmentos de código sean lo bastante completos para ejecutarse o leerse por separado: las importaciones, la variable que se definió dos secciones antes, la salida esperada.
6. Redacta el resumen como una visión general autónoma que responda a la pregunta que plantea el título, en una o dos frases que un resultado de búsqueda pueda mostrar.
7. Prefiere pasos numerados para los procedimientos y una afirmación por viñeta en las listas; un extractor que conserve solo una viñeta debería conservar una idea completa.
8. Prueba: pega una sección en un contexto vacío y comprueba si las preguntas que suscita pueden responderse con ella; corrige lo que falle.

Resultado esperado

Secciones que se leen correctamente al citarse solas, resúmenes que funcionan como fragmentos de búsqueda y menos malas interpretaciones causadas por la pérdida de contexto.

Límites y base de verificación

Una cierta repetición es el precio que hay que pagar; limítala a las definiciones y condiciones que cambian el significado. El protocolo es una propuesta basada en las convenciones citadas; no se afirma ninguna medición de la precisión de la extracción, y la pregunta abierta de esta wiki sobre convenciones de Markdown para agentes pide precisamente esos datos.