kdeps documentation style guide

This guide governs every page under docs/v2/. It merges the Good Docs Project style guidance with the kdeps house rules. When this guide is silent, fall back to the Google developer documentation style guide.

Content types

Every page is exactly one content type. Pick the type first, then use its skeleton from Contributing to docs.

Type	Answers	Lives in
Concept	"What is it and why does it matter?"	start/
Tutorial	"Teach me by building one example."	examples/
How-to	"How do I do one specific task?"	agent/, workflow/, deploy/, agencies/, llm-server/, registry/
Reference	"What are the exact fields, flags, and values?"	reference/, workflow/resources/
Quickstart	"Get me to a working result fast."	workflow/quickstart, agent/quickstart
Troubleshooting	"Something broke. Fix it."	reference/troubleshooting
Glossary	"Define this term."	reference/glossary

Two modes

The directory is the label. agent/ is agent mode. workflow/, deploy/, and examples/ are workflow mode. On a shared page (start/, reference/), name the mode in the first sentence. Do not add an "Applies to" banner. A CLI reference and the glossary document the CLI and the terms, not a mode.

• Workflow mode - DAG-deterministic request/response pipelines.
• Agent mode - autonomous LLM agents with tool use and memory.

Voice and tone

• Mildly casual, serious but not stiff, direct.
• Second person ("you"), present tense, active voice.
• No opinions, no hype, no marketing adjectives.
• Answer first. Context second. Nice-to-know last (inverted pyramid).

Writing rules

• Sentence case for all titles, headings, list items, and table headers.
• Spell out an acronym on first use per page; established acronyms (URL, HTTP, JSON, YAML, API, CLI, SQL) are exempt.
• Short to medium sentences. Cut every word that has not earned its place.
• Do not cluster more than three nouns. Break with "of", "for", "with".
• No metaphors, idioms, or slang.
• Use full forms, not contractions: "do not", "it is", "cannot".
• State the point in the first sentence of a page or section. No warm-up.
• Do not hedge or apologize. State limits flatly: "X does not support Y."
• Bold only labels (start of a list item or table cell), a term's defining use, and warnings. No bold for emphasis in running prose.
• Refer to one thing with one term, always. Do not alternate synonyms.
• Cap each topic (each H2 section) at roughly 300 words. Split if longer.

Typography - ASCII only

• Hyphens, not em dashes.
• Straight quotes, not curly.
• Three dots, not the ellipsis character.
• Hyphen or asterisk bullets, not Unicode bullets.
• No non-breaking spaces.

Page structure

• Start with a one-sentence summary: "X does Y".
• Diagram before prose for any multi-step or multi-component concept: D2 (```d2 block) for 4+ nodes or branching, ASCII (```text block) for linear flows of 3 nodes or fewer. Do not mix both on one page.
• Write for a working developer. Do not explain programming basics (imports, variables, functions, YAML, curl) or use analogies to them; state what the thing does.
• No audience lines ("this page is for..."), learning objectives, "you will be able to", or end-of-page recaps of what the reader just did.
• State the mode only where it is not clear from the section: a page under agent/ is agent mode and a page under workflow/, deploy/ or examples/ is workflow mode. Shared pages say it in their first sentence.
• Every non-obvious YAML field gets an inline comment explaining purpose and behavior: timeout: 30s # hard stop - returns error, does not retry.
• No dot-notation for config (settings.apiServer.auth). Show the real YAML block.
• Collect every inline link into a See also section at the end.

Procedures

• End every procedure with what the reader should see: the real response, the changed row, or the file that now exists. Run it to get that output; mark text produced by a model as varying.

• One sentence per step, starting with a verb.

• Chunk procedures longer than 10 steps into sub-sections of 5 to 10 steps.

• No more than four sub-steps per step.

• Mark optional steps with a leading Optional:.

• Start conditional steps with the condition: "If you use Docker, ...".

Code examples

• Every example must stand alone. A developer copies it directly into a project without reading the surrounding prose.
• Show the mechanics: where the data goes, what runs next, what the output is.
• Build the kdeps binary with make build; the binary is ./kdeps.

Checklist before merging

• [ ] Page is one content type and follows that skeleton.
• [ ] Mode(s) stated in the first paragraph.
• [ ] Summary sentence is the first line of body text.
• [ ] Diagram precedes prose for multi-step concepts.
• [ ] All acronyms expanded on first use.
• [ ] ASCII typography only.
• [ ] Every topic under ~300 words.
• [ ] See also section present with every inline link.
• [ ] cd docs/v2 && npm run build passes.