Estructura de la documentación de NextPDF

De un vistazo

El manual de NextPDF crece conforme a un contrato fijo. Cada página tiene un único tema, un único modo Diataxis y un único tipo de página. Cada tipo de página incluye un conjunto obligatorio de encabezados de nivel 2. Un conjunto reducido de manifiestos y compuertas mantiene la coherencia estructural a medida que el manual se amplía.

Esta página describe la forma de ese sistema para que cada contribución llegue al lugar correcto. El contrato completo y normativo, que incluye las listas exactas de encabezados, las reglas de citación y el procedimiento paso a paso de cableado de compuertas, reside en el documento de gobernanza interno docs/style/expansion-standard.md. Leer primero esta página y consultar ese documento durante la redacción.

Elegir un tipo de página

Usar esta regla, en orden, para decidir si añadir una página o ampliar una existente:

1. Si el material es un tema distinto que un lector no esperaría encontrar en la página existente, añade una página nueva.
2. Si el material completa un tema que la página existente ya posee, amplía esa página.
3. Si el material es detalle profundo que inflaría una página de instalación, de inicio rápido o de tarea, muévelo a una página aparte y enlázala.
4. En caso contrario, amplía la página existente.

Una vez determinada la existencia de la página, definir su modo Diataxis, que fija el tipo de página:

• Tutorial enseña a quien aprende, por lo que corresponde usar una guía de tareas escrita como recipe.
• How-to ayuda a un lector competente a completar una tarea, por lo que corresponde usar una guía de tareas, una guía de API del servidor o una guía del SDK.
• Reference expone hechos exactos, por lo que corresponde usar una referencia de API o una página de índice.
• Explanation desarrolla comprensión, por lo que corresponde usar una guía de desarrollo o una guía de funcionalidad premium.

El lenguaje sencillo es la base en todos los modos, no un modo en sí mismo.

El catálogo de tipos de página

El contrato del manual reconoce estos tipos. Reutilizar un tipo existente siempre que la página incluya una tabla de API; introducir un tipo nuevo, solo de etiqueta, únicamente para una página sin tabla de API.

• Tipos de índice: section-index, api-index, extension-index.
• Tipo de referencia: api-reference. Reutilízalo para cualquier página con la tabla de API estándar, incluidas las referencias del servidor y del SDK de Python.
• Tipo de explicación: developer-guide. Reutilízalo para la prosa de arquitectura, ciclo de vida y puntos de extensión, incluidas las guías del servidor y del SDK de Python.
• Tipos nuevos solo de etiqueta: premium-feature-guide y task-guide, ambos para páginas sin tabla de API.

Cada página comienza con ## At a glance. Cada página api-reference lleva la tabla de API compartida y el encabezado Development notes. Los encabezados obligatorios son exactamente de nivel 2 y cada uno debe ir en su propia línea; se pueden añadir más encabezados debajo de ellos.

Lista de verificación de redacción

Al escribir una página, cumplir ambas listas de verificación. El estándar interno enuncia cada elemento de forma normativa y enlaza el estándar en el que se apoya.

Amabilidad con el desarrollador:

• Tomar los ejemplos ejecutables de examples/ o tests/Cookbook, y dar a cada bloque delimitado una cadena de información title=.
• Indica los requisitos previos en el front-matter y en la apertura.
• Muestra la salida esperada de cualquier ejemplo que produzca una.
• Mantener los bloques listos para copiar y pegar: un solo lenguaje por bloque, nombres completos en el primer uso y sin caracteres de prompt al final.
• Mostrar código seguro de forma predeterminada: los ejemplos de producción usan try/catch con la excepción de NextPDF más específica y nunca un catch vacío.
• Terminar con enlaces de continuación y definir el campo related: del front-matter.

Preparación para la traducción:

• Escribir una sola idea por oración para que la traducción automática no se desborde.
• Mantener cortos los encabezados y las etiquetas, porque la mayoría de los idiomas de destino se expanden.
• Evitar los modismos.
• Mantener en formato de código los nombres de símbolos, las claves de configuración, las opciones de la CLI y los nombres de excepciones; los nombres de estándares como PDF/A-4, PAdES y eIDAS nunca se traducen.
• Definir i18n_ready y xliff_segments de forma honesta, y escribir en Unicode NFC.

Para el estilo de voz, los ejemplos de código, la terminología y la citación, seguir la hoja de anulaciones de estilo ratificada a la que hace referencia el estándar interno.

Cableado de las compuertas

Una página nueva se cablea mediante un procedimiento ordenado:

1. Genera el andamiaje de la página de forma que su front-matter coincida con el esquema del sitio.
2. Redacta el cuerpo según los encabezados obligatorios del tipo de página.
3. Añade una entrada { path, owner, kind, headings[] } a docs/manual-contract.json. La ruta es relativa a src/content/docs, usa barras diagonales y no lleva barra inicial ni ...
4. Para una referencia de API, añade los símbolos de la página a docs/api-coverage-manifest.json; cada símbolo debe aparecer en la página y existir en el código fuente.
5. Actualiza docs/source-manifest.json únicamente cuando la página provenga de un repositorio de origen nuevo.
6. Añade la página al grupo correcto de la barra lateral en astro.config.mjs como una entrada explícita.
7. Añade una fila de cobertura de localización con las diecisiete celdas de localización fijadas en missing para una página solo en inglés.
8. Ejecuta las compuertas de documentación, la compilación y el presupuesto de rendimiento.

Las páginas propiedad del sitio residen bajo src/content/docs, definen owner como nextpdf-docs y nunca llevan un marcador de agregación. Las páginas agregadas provienen de un repositorio de origen, y su indicador de publicación reside en el front-matter de origen; por eso se editan allí, no aquí.

Consulta también

• Integraciones: el ejemplo trabajado más amplio de la forma del manual a lo largo de muchos paquetes.
• El documento de gobernanza interno docs/style/expansion-standard.md contiene el contrato completo: las listas exactas de encabezados para cada tipo de página, las reglas de citación y el procedimiento completo de cableado de compuertas.