Skip to content
pcreative Commerce

pcreative Commerce documentation

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.

How it is organised, and why

Section titled “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?

Folder For whom Answers
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: 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

Section titled “The reference is not written: it is generated”
Terminal window
node scripts/generar-referencia.mjs

It reads the code and rewrites referencia/api.md, variables-entorno.md, tareas-programadas.md and modulos.md. 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.

When you add a feature

Section titled “When you add a feature”
  1. Comment the route: a /** GET /admin/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

Section titled “Index”

Getting started

Guides (all)

Reference

Explanation