Documentation standards

Conventions for this documentation set. They exist so that pages written months apart read as though one person wrote them, and so that a reviewer has something concrete to check against.

The baseline is the Google developer documentation style guide. Where this page is silent, follow Google. Where it disagrees with Google, this page wins, and each divergence below says why.

Voice and tense

Address the reader as "you". Write about the product in the third person. Do not use "we" to mean the product, and do not use it to mean the reader either.

Use present tense for behaviour and imperative for instructions.

The endpoint returns an empty array when nothing matches.

Copy the token into .env.

Not:

The endpoint will return an empty array if nothing should match.

You should now copy the token into .env.

Avoid "simply", "just", "easy" and "obviously". If a step is easy the reader finds out by doing it; if it is not, the word has told them the problem is theirs.

Structure

Lead with what the reader came for. Background goes after the procedure, or on a different page.

One task per page. If a page needs two verbs in its title, it is two pages.

Headings are sentence case. Procedures are numbered, unordered material is bulleted, and anything that runs to three or more parallel facts is a table.

Do not bullet prose. A list of full sentences that flow into each other is a paragraph that has been chopped up, and it reads worse than the paragraph did.

Accuracy

Every documented parameter, default and response field is checked against the source before it ships. Where behaviour is surprising, document the behaviour rather than the intention.

This set documents several things the product does not do well: the sync endpoint's hard-coded paths, the absence of authentication, the fixed seasonality window. Recording them is not disloyalty to the product. A reader who hits an undocumented limitation stops trusting the whole document, and the cost of that is much higher than the cost of admitting the limitation.

Do not invent example values that could be mistaken for real ones. Examples use plausible but obviously synthetic figures.

Terminology

Pick one term per concept and never vary it for elegance.

Use	Not
marketplace	platform, site, channel
listing	card, product page
impressions	views, shows
cost price	purchase price, cost of goods, COGS
sync	import, refresh, update
product	item, SKU (when referring to the thing rather than its identifier)

"SKU" means the identifier, not the product. A product has a SKU.

Formatting

Code, filenames, paths, field names and literal values go in backticks. UI labels go in bold. Nothing goes in italics for emphasis.

Write HTTP methods in caps with the path in a code block:

GET /api/profit/daily

Every endpoint reference carries, in this order: the method and path, one sentence on what it does, a parameter table, a response field table, and at least one runnable example. Sections that would be empty are omitted rather than filled with "None".

Use admonitions for information that changes what the reader does. A note that merely adds colour belongs in the prose or nowhere.

Numbers and units

Spell out zero through nine in prose, use digits from 10 up, and always use digits with a unit or in a table.

Currency figures in examples carry no currency symbol, because the product is currency-agnostic and takes whatever the marketplace reports.

Links

Link text describes the destination. Never "click here", never a bare URL in running text.

Internal links are relative, so that mkdocs build --strict catches a broken one before it is published. That check is why the CI build uses --strict.

Review checklist

Before merging a change to docs/:

• [ ] Every parameter, default and field verified against the current source
• [ ] Procedures followed start to finish on a clean environment
• [ ] Examples executed, and their output matches what is shown
• [ ] Terminology matches the table above
• [ ] mkdocs build --strict passes
• [ ] No new instance of "simply", "just", "easy" or "please"