Saltar al contenido
pcreative Commerce

Documentación de pcreative Commerce

Cómo instalar, usar y ampliar pcreative Commerce: guías paso a paso, referencia y explicaciones, escritas junto al código.

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.

Dos idiomas

El inglés es el idioma principal del producto, y la documentación lo sigue:

  • El inglés vive en docs/, con sus carpetas getting-started/, guides/, reference/ y explanation/.
  • El español vive aquí, en docs/es/, con las mismas páginas en las carpetas de abajo.

Cada página nueva va en los dos, y los dos dicen lo mismo.

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?

CarpetaPara quiénResponde 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, docs/interno/, que no se publica ni viaja en el paquete: 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 cuatro páginas en cada idioma: referencia/api.md, variables-entorno.md, tareas-programadas.md y modulos.md en español, y docs/reference/api.md, environment-variables.md, scheduled-jobs.md y modules.md en inglés. 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. Con --comprobar no escribe nada: dice si lo publicado coincide con el código, y es lo que corre en el CI para que la referencia no se quede atrás en silencio.

Al añadir una funcionalidad

  1. Comenta la ruta: un bloque /** GET /gestion/loquesea — qué hace. */. Con eso ya entra sola en la referencia.
  2. Si trae variable de entorno, ponla en el .env.example que toque.
  3. 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.
  4. Vuelve a generar la referencia.

Lo demás se mantiene solo.

Índice

Empezar

Guías (todas)

Referencia

Explicación

Empezar: la primera vez

Para quien llega y todavía no tiene nada montado. Se siguen en orden.

En esta página

Dos idiomasCómo está organizada, y por qué asíLa referencia no se escribe: se generaAl añadir una funcionalidadÍndice