Contributing¶

Every page starts as Markdown in docs/, in this site's source repository. It gets reviewed in a pull request and goes live on docs.qcloud.systems once merged.

From notes to a published page¶

Pick the area. Where does the page belong?

If the page…	It goes in
explains how something works or what was learned	`engineering-notes/<topic>/`
walks someone through running a service themselves	`self-hosting/<topic>/`
documents a QCS product for customers	`products/<stage>/`

Start from a template. Copy the matching template into the folder and name the file in kebab-case.md.
Add it to the navigation in mkdocs.yml, under its section. Then update that section's index.md: move the topic from Planned pages to Published.
Preview it. MkDocs runs inside a Python virtual environment in .venv/, which is never committed. Create it once per machine or codespace:
```
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```
Then, in every new terminal, activate it and serve:
```
source .venv/bin/activate    # the prompt starts with (.venv)
mkdocs serve                 # http://127.0.0.1:8000, reloads on save
```
mkdocs: command not found means the environment is not active in that terminal. Run mkdocs build --strict before opening a pull request; it is the same check CI runs.
Open a pull request. CI runs a strict build. Broken links, missing pages and anything that looks like a credential fail the check before the page can ship.

Review checklist¶

Each page is checked for:

Accuracy. Commands run as written, versions are current, and nothing relies on a deprecated flag or API.
Safety. Placeholders like <bucket-name> and <your-api-key> instead of real values, with no account IDs, hostnames or internal IPs.
Placement. It sits in the right area and links forward along the learning path.
Clarity. A description in the front matter, tags, and headings that make sense in the table of contents.

This site is public

The repository and the site are both public, and git history keeps everything that was ever pushed. Strip credentials, client names and internal details from notes before they are committed. The build blocks common secret formats, but it cannot catch everything.

Writing style¶

Write for someone smart who hasn't done this before.
Lead with the command, then explain it.
Keep Lessons learned honest: what broke is often the most useful part.
Prefer one topic per page. Split a page once it needs more than one goal.