Skip to content
pcreative Commerce

pcreative Commerce documentation

How to install, run and extend pcreative Commerce: step-by-step guides, reference and explanations, written next to the code.

This folder is the source of the documentation. What gets published on the web comes from here: it is written next to the code, versioned with it and reviewed in the same place, so it cannot wander off on its own.

Two languages

English is the product's primary language, and the documentation follows it:

  • English lives here, in docs/, with the folders below.
  • Spanish lives in docs/es/, with the same pages under their own folder names: empezar/, guias/, referencia/ and explicacion/.

Every new page goes in both, and both say the same thing.

How it is organised, and why

Four folders, by what someone came for — not by what the text is about. It is the Diátaxis framework, and it answers the question that kills any documentation as it grows: where do I put this new page?

FolderFor whomAnswers
getting-started/someone arriving for the first time"walk me through it the first time"
guides/someone already inside with a task"how do I do X"
reference/someone who needs an exact fact"what parameters does this take"
explanation/someone who wants to understand"why does it work this way"

Mixing them is the usual mistake: a tutorial with reference notes stops being followable, and a reference with explanations stops being consultable.

There is a fifth, interno/, which is not published and does not travel in the package: working notes, competitive analysis and to-dos. If something there is useful to the public, it is rewritten and moved; it is not published as-is.

The reference is not written: it is generated

node scripts/generar-referencia.mjs

It reads the code and rewrites four pages in each language: reference/api.md, environment-variables.md, scheduled-jobs.md and modules.md in English, and docs/es/referencia/api.md, variables-entorno.md, tareas-programadas.md and modulos.md in Spanish. Do not edit them by hand: they get overwritten.

It is done this way because the reference is the part that grows most and lies first. Written by hand it ages with every new feature; six months in nobody trusts it, then it stops being read, and then it stops being maintained.

It also says what is missing: every route without a header comment comes out marked as undocumented, and every environment variable not in a .env.example comes out flagged. Debt stops being a feeling and becomes a number you can bring down.

With --estricto it exits with an error if that debt exists, so you can watch it from CI the day it matters. With --comprobar it writes nothing: it tells you whether what is published matches the code, and that is what runs in CI so the reference cannot fall behind silently.

When you add a feature

  1. Comment the route: a /** GET /gestion/whatever — what it does. */ block. With that it enters the reference on its own.
  2. If it brings an environment variable, put it in the right .env.example.
  3. Write by hand only what takes judgement: the "how to use it" guide if it is not obvious, and the "why it is this way" explanation if the decision is not.
  4. Regenerate the reference.

The rest maintains itself.

Index

Getting started

Guides (all)

Reference

Explanation

Getting started: the first time

For someone who has just arrived and has nothing set up yet. Follow them in order.

On this page

Two languagesHow it is organised, and whyThe reference is not written: it is generatedWhen you add a featureIndex