vanillagreencom/kendex/docs-writing

Docs Writing

A repository's internal design documentation holds what the code cannot show: the principle behind a design, the rule an agent could break without noticing, a decision with its reason, a convention that differs from a tool default, and a pointer to the canonical code. Everything else lives in the code, its comments, the tests and git history.

This skill governs repository markdown and documentation HTML. It states one writing standard, one repository layout, what each file type holds, and the finished example an author reads before writing one. Policy and operating documents also follow § Writing.

Do not hand-copy code-owned inventories or defaults. A reference may define a contract not declared elsewhere, or explain semantics beside a link to its declaration. A generated reference may show declared values. A claim that a checker enforces something names the checker.

The standard

• Write short sentences. Put one idea in each sentence.
• Use active voice and name the actor. Say what the code does, not what is done.
• Use plain words. Basic technical terms are fine: CLI, API, repo, PR, hook, lock, glob.
• Use one term per thing, the same term every time.
• State each fact once. Point at the first statement instead of repeating it.
• Write a heading that names the subject. A heading never makes a claim.
• Write in the present tense. A rule states what holds.
• Delete sales language, quips, metaphors, and hedges.
• Delete a sentence nothing acts on.

Layout

This is the default repository layout. A rewrite moves what it finds onto it. A material departure needs an owner-approved decision under the decider bar. A supported naming or location variant needs no separate decision. A rewrite keeps and cites an approved departure.

Nothing else lives under docs/. A software implementation plan, research report, measurement or handoff is tracker or tmp/ content (§ Plans and research). An assistant home's policy, memory and session records keep their owning locations and reading routes; when writing or rewriting those records, read references/assistant-home.md. Product content a repository ships to its users, such as a help site, legal pages or an adapter reference, stays and is named in that repository's AGENTS.md. A skill's reference docs stay in its references/.

Reference rules

• The root AGENTS.md gives each principle doc a task trigger, or routes to a nested AGENTS.md that gives the local trigger: "Before writing a plugin: docs/architecture/plugins.md".
• A nested AGENTS.md names the principle doc for its folder. Codex reads every AGENTS.md on the path to the working directory. Claude Code loads a nested AGENTS.md when it reads a file there. Copilot reads the nested file when it opens files there.
• The Copilot review instruction files point the review bot at the same principle docs for the matching paths; the bot-instructions skill renders them.
• Decision records are not listed in AGENTS.md. Review and dev workflows find them by keyword with decisions search, and a code comment cites a decision ID only where that code carries out the choice.
• A code comment holds a local reason or an external cause at its site, per the code-quality skill's SKILL.md § Comments and Prose, and nothing points to it.
• A README links to a doc only when a person needs it, such as "Writing a plugin".
• An architecture topic document is referenced when a "Read when" line names the task that triggers reading it. A filename in a list, a link from another doc or a mention in prose is not a task route. Delete an architecture topic index that only repeats these routes. This rule does not replace decision discovery, skill reference loading or human navigation. Keep the decider index. Generated examples use their generator inventory; human pages a site loads use the product-content declaration in AGENTS.md.

Per file type

Each section says who reads the file, what it holds, and what it never carries. Each finished example under examples/ ends with a contrast drawn from a real failure and one sentence on why that failure fails the reader.

Before writing a file, find its type in this table, then read its section and its example. The first row whose path matches wins; * matches across /. Shape names the structural rules that apply to the type: order is the numbered section order, and value-table is the rule against a value table. The commit-guards md-type lane checks them.

One home per fact

For an internal design claim, ask the questions below in order and stop at the first yes. First classify user help, operating steps, skill procedures and reference contracts by their file-type section.

1. Is it one option kept over a named rejected alternative, whose reason the code cannot show and whose reasons and alternatives a doc's rules cite rather than repeat? A decision record: the choice, why, the rejected option and the revisit trigger, under the decider bar. Example: examples/decision.md, one dismiss owner kept over per-component handling, cited by the design-system doc's rule.
2. Is it the approach one reader's task runs under, or a rule followed while doing it? An architecture doc: the approach, its why and its rules, stating the current actionable rule and citing any decision it rests on by ID without repeating its reasons or alternatives. Examples: examples/architecture-plugins.md, a surface goes in a plugin and never imports another; examples/architecture-design-system.md, every value a component draws comes from the token file.
3. Neither. A feature's behaviour, what a page, key or button does, lives in the code, its tests and the tracker item that asked for it. Counter-example: examples/behaviour-spec.md, a window written up control by control, with where each line goes.

Decision records

Read by a reviewer or agent about to reverse a choice. The bar, the format and the workflows are the decider skill's; this skill ships no second format. A principle doc states the current actionable rule and cites the decision ID. It does not repeat the decision's reasons or alternatives. Example: examples/decision.md.

Runbooks

Read by an operator maintaining or recovering a running system. A procedure names the task and when to use it, the target environment, required access and tools, and approval for effects that change service or data. Put steps in execution order. Give each step its expected reading and the condition that permits the next step. Name the source of the reading, such as a status page, command result or log. An unavailable reading is unresolved, not success.

State when the operator stops, how to leave or restore the system, and who receives a failure with its evidence. Describe recovery only where the system's current operating contract supports it. Finish with the end-state check and cleanup of temporary access, files or changed settings; preserve evidence until its handoff is checked. Verify instructions against the current tools and operating contract. Link to declarations and tool help instead of copying their inventories or defaults.

Never: build and test instructions for package development, design rationale, incident history or a record of one run. Those facts keep their homes under § Layout and § Plans and research. Example: examples/runbook.md.

Documentation HTML