Escribir documentación técnica en reStructuredText con ejemplos reales y comprobar la compilación

## Explica lo que el lector necesita y deja los detalles internos al código Escribe para quienes necesitan comprender y utilizar el comportamiento documentado. Explica los conceptos con claridad y de la forma más concisa posible. Incluye detalles de bajo nivel cuando ayuden al lector a tomar una decisión, pero deja los aspectos internos de implementación muy profundos en el código fuente. - Describe la firma de un método solo cuando sea esencial para utilizarlo correctamente. - Documenta los argumentos y las opciones del comando que afectan al flujo de trabajo principal, no todos los modificadores disponibles. - No vuelvas a explicar un error o una excepción cuando su mensaje en el código ya indique la causa y la solución. - Prioriza una explicación centrada, un ejemplo realista y un enlace a detalles relacionados frente a un catálogo exhaustivo. ## Elige la rama según el tipo de cambio y los datos de versiones Nunca fijes en el código la lista de versiones mantenidas. Consulta los metadatos de versiones oficiales del proyecto antes de elegir una rama de destino y aplica después las reglas del tipo de cambio de forma coherente. - Las correcciones de errores se dirigen a la rama mantenida más antigua que contenga el error. - La documentación de una función nueva se dirige a la rama que introdujo esa función. Si esa rama ya no recibe mantenimiento, utiliza la siguiente rama que siga mantenida. - Las erratas, reformulaciones, reestructuraciones y otros cambios no funcionales se dirigen a la rama mantenida más antigua. - La documentación de subproyectos con versiones independientes sigue su propia política declarada; cuando así se especifique, dirige todos los cambios a la rama mantenida más antigua, incluidas las funciones nuevas. Registra el tipo de cambio y los datos de mantenimiento utilizados para tomar la decisión. Si los metadatos de versiones no están disponibles o son ambiguos, no adivines la rama. ## Usa siempre los mismos signos de título y el mismo ancho de línea Utiliza de forma coherente los caracteres de subrayado de cada nivel de encabezado: signos igual para el nivel 1, guiones para el nivel 2, virgulillas para el nivel 3, puntos para el nivel 4 y comillas dobles para el nivel 5. Cada subrayado debe abarcar todo el texto del encabezado. Aplica las excepciones de encabezado para rutas concretas que declare el repositorio. Ajusta el texto a 80 caracteres, salvo en tablas, URL y líneas aisladas cuando el ajuste reduzca la legibilidad. Coloca las viñetas al principio de la línea. No dividas un fragmento en negrita o cursiva entre varias líneas. Para el código en línea, utiliza pares de comillas invertidas dobles. En ejemplos de código con el lenguaje predeterminado, utiliza la forma concisa de dos puntos dobles, salvo que el marcador quedara solo en su línea. Utiliza una directiva code-block explícita cuando sea necesario indicar el lenguaje o el contexto de renderizado. ## Unifica la sangría de las directivas y la forma de escribir enlaces Sangra el contenido de las directivas con cuatro espacios. Deja una línea en blanco después de un marcador de dos puntos dobles y antes de su contenido, así como antes y después de cada directiva. Alinea las líneas de continuación de un elemento de lista multilínea con el inicio de su texto. Utiliza la admonición estándar que corresponda al mensaje: note, tip, warning, caution o seealso. Para contenido añadido en una versión y contenido obsoleto, utiliza las directivas específicas con la versión correspondiente y una explicación breve. Utiliza rutas de documento absolutas en los enlaces internos. Para enlazar una sección concreta, utiliza una referencia cruzada con etiqueta. Nunca utilices una ruta interna relativa. Para sitios externos, coloca los destinos de enlace con nombre al final del archivo en vez de insertar URL en línea dentro del texto. Utiliza los roles específicos del sistema de documentación para las clases, los métodos, las funciones y los tipos integrados de la API del lenguaje. ## Muestra los ejemplos de configuración YAML, XML y demás siempre en el mismo orden Cuando una función admita varios formatos de configuración, muestra todos los formatos compatibles mediante una directiva configuration-block. Mantén un orden común en todo el repositorio para que los lectores puedan comparar páginas sin tener que aprender de nuevo la disposición. - Para servicios y configuración general, utiliza YAML, XML y después el formato del lenguaje de programación. - Para enrutamiento, validación y mapeo de objetos, utiliza atributos, YAML, XML y después el formato del lenguaje de programación. - Para recursos de traducción, utiliza XML, YAML y después el formato del lenguaje de programación. Utiliza pestañas normales solo para contenido paralelo que no sea configuración, como herramientas o flujos de trabajo alternativos. Cuando los ejemplos difieran entre aplicaciones integradas con el framework y aplicaciones independientes, utiliza identificadores de lenguaje distintos para que el renderizador y el lector puedan distinguir los contextos. ## Escribe ejemplos de código con nombres realistas y un comentario con el archivo Sigue las normas de codificación del lenguaje de destino y las prácticas recomendadas establecidas por el proyecto. Utiliza nombres y situaciones realistas en lugar de palabras de relleno que oculten la intención. Emplea dominios reservados para ejemplos y el nombre de proveedor de muestra que use el repositorio. - Ajusta las líneas de los bloques de código a 85 caracteres cuando resulte práctico. - Sangra los ejemplos con cuatro espacios, incluido YAML. - Incluye declaraciones de espacio de nombres e import cuando ayuden a ejecutar el ejemplo o aclarar los tipos. - Comienza un bloque de código con un comentario que indique el nombre del archivo; no añadas una línea en blanco, salvo que la línea siguiente también sea un comentario. - Antepón un marcador de indicador a cada comando de shell. - Usa la forma de comentario propia del lenguaje cuando contraigas bloques omitidos. - Utiliza puntos suspensivos sin marcadores de comentario al acortar una parte de un valor en la misma línea. - Conserva las reglas de espaciado específicas del formato, incluidos los espacios dentro de los mapeos YAML en línea cuando sean necesarios. Un ejemplo debe enseñar la vía compatible sin fingir que constituye una implementación completa para producción. No omitas un requisito previo cuya ausencia haría fallar el código mostrado. ## Escribe en inglés estadounidense sencillo y evita palabras como “simply” Escribe en inglés estadounidense. Utiliza mayúsculas de título en los encabezados de sección: escribe con mayúscula inicial la primera y la última palabra, así como las palabras principales, y deja en minúscula las palabras funcionales cortas, salvo cuando comiencen el título. Dirígete al lector como “you” en vez de hablar como “we”. Utiliza pronombres neutros en cuanto al género. Prefiere la voz activa, el vocabulario básico y las frases directas que funcionen para un público internacional. Se permiten las contracciones. No uses la coma de Oxford. Evita expresiones idiomáticas y palabras condescendientes como “obviously”, “simply”, “just”, “easy”, “clearly”, “trivial” y “of course”. Estas palabras pueden ocultar una explicación insuficiente y desanimar al lector. Todas las imágenes necesitan un texto alternativo conciso que empiece con mayúscula y termine con un punto. No comiences con “A screenshot of” ni “Diagram of”. Explica los diagramas complejos en el texto circundante en vez de forzar todos los detalles en el texto alternativo. ## Antes de terminar, compila la documentación y revisa avisos y enlaces rotos Escribe los directorios con una barra final y las extensiones de archivo con un punto inicial. Utiliza una raíz de proyecto de ejemplo neutra, como `your-project/`, en los árboles de directorios. Mantén coherentes los nombres de archivo, las rutas, los comandos y los destinos de referencia entre el texto y los ejemplos. Antes de considerar completo un cambio de documentación: 1. Instala las dependencias de compilación de la documentación en el espacio de trabajo de compilación designado. 2. Ejecuta el comando de compilación documentado por el repositorio. 3. Sirve temporalmente el resultado generado cuando sea necesaria una inspección visual. 4. Comprueba en las páginas modificadas las advertencias, las referencias rotas, las directivas mal formadas, el renderizado del código, la jerarquía de encabezados y las descripciones de imágenes. 5. Confirma que la rama de destino elegida sigue correspondiendo al tipo de cambio y a los metadatos de mantenimiento actuales. No informes de un resultado satisfactorio basándote solo en la inspección del código fuente cuando el repositorio proporcione un mecanismo de compilación de la documentación.