Documentación de pcreative Commerce

Esta carpeta es la fuente de la documentación. De aquí sale lo que se publica en la web: se escribe junto al código, se versiona con él y se revisa en el mismo sitio, así que no puede irse por su lado.

Cómo está organizada, y por qué así

Cuatro carpetas, según para qué viene alguien — no según de qué trata el texto. Es el marco Diátaxis, y resuelve la pregunta que mata cualquier documentación que crece: ¿dónde meto esta página nueva?

Carpeta	Para quién	Responde a
`empezar/`	quien llega por primera vez	«acompáñame la primera vez»
`guias/`	quien ya está dentro y tiene una tarea	«cómo hago X»
`referencia/`	quien necesita un dato exacto	«qué parámetros acepta esto»
`explicacion/`	quien quiere entender	«por qué funciona así»

Mezclarlas es el error habitual: un tutorial con notas de referencia deja de poder seguirse, y una referencia con explicaciones deja de poder consultarse.

Hay una quinta, interno/, que no se publica: notas de trabajo, análisis de competencia y pendientes. Si algo de ahí sirve al público, se reescribe y se mueve; no se publica tal cual.

La referencia no se escribe: se genera

node scripts/generar-referencia.mjs

Lee el código y reescribe referencia/api.md, variables-entorno.md, tareas-programadas.md y modulos.md. No los edites a mano: se pisan.

Se hace así porque la referencia es la parte que más crece y la primera que miente. Escrita a mano envejece con cada funcionalidad nueva; a los seis meses nadie se fía, entonces deja de leerse, y entonces deja de mantenerse.

Además dice lo que falta: cada ruta sin comentario de cabecera sale marcada como sin documentar, y cada variable de entorno que no esté en un .env.example sale señalada. La deuda deja de ser una sensación y pasa a ser un número que se puede bajar.

Con --estricto termina en error si esa deuda existe, para poder vigilarla desde el CI el día que interese.

Al añadir una funcionalidad

Comenta la ruta: un bloque /** GET /admin/loquesea — qué hace. */. Con eso ya entra sola en la referencia.
Si trae variable de entorno, ponla en el .env.example que toque.
Escribe a mano solo lo que exige criterio: la guía de «cómo se usa» si no es evidente, y la explicación de «por qué es así» si la decisión no lo es.
Vuelve a generar la referencia.

Lo demás se mantiene solo.

Índice

Empezar

Guías (todas)

IA: conectarla · chat en la tienda · agentes de IA
Temas: instalar · crear uno
Escribir un plugin
Copias de seguridad

Referencia

Explicación