Redactar y revisar la documentación

Cadrumo es una aplicación española de presentación de declaraciones tributarias. La AEAT es la autoridad tributaria española externa. Esta guía le muestra cómo hacer un cambio en la documentación y llevarlo a través de la revisión. Existen cuatro superficies de documentación: el markdown del repositorio, los docstrings dentro del código y dos referencias generadas: una para la interfaz de programación de aplicaciones (API) y otra para la interfaz de línea de comandos (CLI).

Elige la superficie adecuada

Dónde hagas un cambio depende de lo que estés cambiando:

  • El markdown del repositorio se escribe a mano. Edita el README o una guía bajo docs/ directamente.

  • Los docstrings son la única fuente de la referencia de la API. Edita el docstring en el código y deja que Sphinx (la herramienta de construcción de la documentación) lo renderice. Nunca copia una firma en el texto a mano.

  • La referencia de la API la genera la herramienta dev.docs.apidocs a partir de los módulos del código. Escribe páginas stub (ficheros de referencia de marcador de posición); no edites esas páginas a mano: regenérelas.

  • La referencia de la CLI se genera a partir del árbol de comandos (el conjunto completo de comandos y subcomandos de la CLI). No la edites; regenérela con los comandos que se indican a continuación.

Definiciones de los términos de generación

Al trabajar con documentación generada, conviene entender la siguiente terminología:

  • apidocs: la herramienta de línea de comandos dev.docs.apidocs, ubicada en dev/docs/apidocs/. Es el generador de stubs de la referencia de la API del proyecto, que recorre el árbol de módulos del código para determinar la estructura de la API y genera los ficheros de referencia correspondientes.

  • stub: una página stub de referencia es un fichero RestructuredText (.rst) autogenerado y de marcador de posición bajo docs/api/. Cada fichero stub corresponde a un módulo o paquete de Python y contiene las directivas automodule que indican a Sphinx que extraiga el docstring vivo del código. Los stubs se guardan en el repositorio, pero nunca deben editarse a mano.

Para reconstruir las superficies generadas y verificarlas, ejecuta:

python -m dev.docs.apidocs scaffold  # writes the API stub pages
just docs-build                        # builds the full documentation site
just docs-serve                  # serves the site with live reload (auto-picks a free port)
just docs-check                  # validates cross-references, stubs, and CLI output

just docs-serve abre una vista previa que reconstruye y refresca el navegador cada vez que cambia una página bajo docs/ o un docstring bajo src/cadrumo/. Se enlaza a todas las interfaces en un puerto no predeterminado (para que un contenedor, una VM o un equipo de la LAN pueda alcanzarlo) y elige automáticamente un puerto libre; pasa just docs-serve 9000 para fijar uno. Ejecutarlo por segunda vez se conecta a la vista previa ya en marcha en lugar de colisionar con ella. Añadir o eliminar un módulo sigue necesitando python -m dev.docs.apidocs scaffold para refrescar el conjunto de stubs.

just docs-check falla ante una referencia cruzada rota, un stub que falta o una referencia de comando que ya no coincide con los comandos.

Llevar un cambio narrativo a través de la revisión

Un cambio en el README o en una guía bajo docs/ avanza por una revisión por etapas. Cada etapa tiene un revisor distinto, y cada una se completa antes de que empiece la siguiente:

  1. Esquema. Esboce el documento como títulos e intenciones de cada sección. Asigna a cada página un tipo de Diataxis: Diataxis es un marco de documentación que clasifica las páginas en cuatro clases: tutorial, guía práctica, referencia o explicación.

  2. Refinamiento. Un revisor sin contexto del proyecto lee solo el esquema y confirma que alguien nuevo entendería qué aporta cada sección. Revisa hasta que todas las secciones lo superen.

  3. Contexto. Los investigadores reúnen los datos, los comandos, las rutas y las ubicaciones del código que necesita cada sección.

  4. Redacción. Los autores escriben cada sección a partir del contexto reunido y de las reglas de estilo de prosa del proyecto.

  5. Revisión técnica. Los revisores verifican cada comando, flag, ruta y nombre de clase contra el código.

  6. Revisión editorial. Un revisor sin contexto del proyecto comprueba la redacción contra las mismas reglas de estilo de prosa.

  7. Aprobación. El cambio se incorpora una vez que las revisiones técnica y editorial lo superan.

Mantén los roles separados

Mantén la investigación, la redacción y la revisión en manos distintas. Cuando reúnas contexto, no escribas el texto final. Cuando redactes, escribe a partir del contexto reunido y no inventes datos. Cuando revises la calidad editorial, trabaja solo con el documento, sin el código. La separación mantiene honesto cada juicio.

No codifique metadatos del proceso

Las rutas, los nombres de fichero y el contenido de la documentación llevan solo nombres de dominio y de tema. No incorpores en ellos el marco de documentación ni el proceso de gestión del proyecto. Eso descarta los identificadores de wave, fase y step, los identificadores de plan y de registro de decisiones, y las etiquetas de agente o de campaña. El lector debe ver el producto, no el proceso que lo construyó.