LLM-Server/docs/agents/writing-docs.md

Writing docs

How to write and update this repo's docs and code comments. The source is the truth: docs explain why and point at the source for what.

Rules

1. Source-of-truth line. Every doc outside docs/research/ and docs/agents/ opens with a > **Source of truth:** … line. It names the files, services or keys the doc explains and says the source wins on disagreement. In the body, name keys and flags (LLAMA_PARALLEL, --cache-reuse) and leave their values in the source. When a doc and its source disagree, fix the doc in the same change.

2. The README index is the doc map. Every new doc gets a row in README.md's Docs table.

3. Code comments are pointers. In docker-compose.yml, .env.example and scripts/, a comment is a one-line # see docs/<file>.md#<section> pointer, and the explanation goes in that doc section. Two things stay inline as one line, next to the pointer:

   • a warning about data loss, security, or an edit that breaks the stack or a script
   • on .env.example keys that update.sh fills in, the marker "auto-filled by update.sh — leave blank"

   A ponytail: note becomes a pointer too, with its reasoning moved into the doc.

4. A source change carries its doc. When you change code that has a pointer, update the doc section it names in the same change.

5. docs/research/ is frozen history. New research goes in a new file plus a row in docs/research/README.md. When a research doc goes stale, change its status in that index and leave the file itself untouched.

Terminology follows CONTEXT.md. For a term that isn't there, see domain docs → New or conflicting terms.

Done when

• every pointer in the code you touched resolves to an existing heading
• every doc you touched opens with its source-of-truth line
• no doc you touched restates a value from its source