Redacció i revisió de la documentació

Cadrumo és una aplicació de presentació d’impostos espanyols. L’AEAT és l’autoritat fiscal espanyola externa. Aquesta guia et mostra com fer un canvi a la documentació i portar-lo per la revisió. Existeixen quatre superfícies de documentació: el markdown del repositori, les docstrings dins del codi font i dues referències generades: una per a la interfície de programació d’aplicacions (API) i una per a la interfície de línia d’ordres (CLI).

Tria la superfície adequada

On fas un canvi depèn d’allò que canvies:

  • El markdown del repositori s’escriu a mà. Edita el README o una guia dins de docs/ directament.

  • Les docstrings són la font única de la referència de l’API. Edita la docstring al codi font i deixa que Sphinx (l’eina de construcció de la documentació) la representi. No copiïs mai una signatura a la prosa a mà.

  • La referència de l’API la genera l’eina dev.docs.apidocs a partir dels mòduls del codi font. Escriu pàgines stub (fitxers de referència de reserva); no editis aquestes pàgines a mà: torna-les a generar.

  • La referència de la CLI es genera a partir de l’arbre d’ordres (el conjunt complet d’ordres i subordres de la CLI). No l’editis; torna-la a generar amb les ordres següents.

Definicions dels termes de generació

Quan treballis amb documentació generada, comprèn la terminologia següent:

  • apidocs: l’eina de línia d’ordres dev.docs.apidocs, situada a dev/docs/apidocs/. És el generador de stubs de la referència de l’API del projecte, que recorre l’arbre de mòduls del codi base per determinar l’estructura de l’API i genera els fitxers de referència corresponents.

  • stub: una pàgina stub de referència és un fitxer RestructuredText (.rst) autogenerat i de reserva situat dins de docs/api/. Cada fitxer stub correspon a un mòdul o paquet de Python i conté les directives automodule que indiquen a Sphinx que extregui la docstring en viu del codi. Els stubs es desen al repositori, però no s’han d’editar mai a mà.

Per reconstruir les superfícies generades i verificar-les, executa:

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 obre una previsualització que es reconstrueix i refresca el navegador cada cop que canvia una pàgina dins de docs/ o una docstring dins de src/cadrumo/. Escolta a totes les interfícies en un port no predeterminat (perquè un contenidor, una màquina virtual o un equip de la LAN hi pugui accedir) i tria automàticament un port lliure; passa just docs-serve 9000 per fixar-ne un. Si l’executes una segona vegada, s’adjunta a la previsualització ja en marxa en lloc d’entrar-hi en conflicte. Afegir o eliminar un mòdul encara requereix python -m dev.docs.apidocs scaffold per refrescar el conjunt de stubs.

just docs-check falla si hi ha una referència creuada trencada, un stub que falta o una referència d’ordre que ja no coincideix amb les ordres.

Porta un canvi narratiu per la revisió

Un canvi al README o a una guia dins de docs/ avança per una revisió per etapes. Cada etapa té un revisor diferent i cadascuna es completa abans que comenci la següent:

  1. Esquema. Esbossa el document com a títols i intencions de secció. Assigna a cada pàgina un tipus de Diataxis: Diataxis és un marc de documentació que classifica les pàgines en quatre menes: tutorial, guia pràctica, referència o explicació.

  2. Refinament. Un revisor sense context del projecte llegeix només l’esquema i confirma que un nouvingut entendria què aporta cada secció. Revisa fins que cada secció ho superi.

  3. Context. Els investigadors apleguen els fets, les ordres, els camins i les ubicacions del codi font que necessita cada secció.

  4. Redacció. Els autors escriuen cada secció a partir del context aplegat i de les regles d’estil de prosa del projecte.

  5. Revisió tècnica. Els revisors verifiquen cada ordre, indicador, camí i nom de classe contra el codi.

  6. Revisió editorial. Un revisor sense context del projecte comprova la redacció amb les mateixes regles d’estil de prosa.

  7. Aprovació. El canvi s’incorpora un cop passen les revisions tècnica i editorial.

Mantén els rols separats

Mantén la recerca, la redacció i la revisió en mans separades. Quan apleguis context, no escriguis la prosa final. Quan redactis, escriu a partir del context aplegat i no inventis fets. Quan revisis la qualitat editorial, treballa només amb el document, sense el codi base. La separació manté honest cada judici.

No codifiquis metadades de procés

Els camins, els noms de fitxer i el contingut de la documentació només porten noms de domini i de tema. No hi posis el marc de documentació ni el procés de gestió del projecte. Això exclou els identificadors d’onada, fase i pas, els identificadors de pla i de registre de decisions, i les etiquetes d’agent o de campanya. Un lector ha de veure el producte, no el procés que el va construir.