Writing Docs

How a page, README or guide is written and checked: the rules the docs checks hold every page to, and the limits they read.

Read the Rules

Read Docs Rules before writing or editing a page, README or guide: each rule by its id, as the docs checks report it. A section's hook follows Writing Hooks.

Limits

The docs checks read these from tests/docs/limits.toml, and fail when this table differs from it. A file past its line limit is listed in tests/docs/large-files.toml, and so is a page written before the shape rules: each may shrink, never grow.

LimitAt mostWhy
Average hundredths of a link from the root README265Link a page where a reader meets what it explains.
Characters in a table cell60A cell is a few words; more is a section.
Links a reader follows from the root README to a page5Link a page where a reader meets what it explains.
Levels from the home page to a page's deepest heading7The address and the headings are one tree.
Times a package's docs are off its Rust lines to the 0.73.5Docs grow with the code they explain, more slowly.
Characters before two pages may not share a paragraph120Say it once, where it belongs, and link there.
Pages a page with pages under it holds at least3Fewer is a level opened for one or two pages.
Headings under a heading, and at a page's top10Group a longer list a level deeper.
Characters in a hook45It's a heading, and half the tab's title.
Words a hook has at least3A hook says more than its page's name.
Words in a non-root README outside docs/120A README is a map; how it works is a page.
Characters in a list item400An item is a line or two; more is a section.
Lines in a Markdown file500Split a longer page by subject.
Pages under a page in the site's tree10Group a longer list in a folder.
Characters in a paragraph600More is two subjects: two sections.
Links under a README's ## Code5Name the entry points, three or so.
Lines in a Rust file1,000Split where a responsibility ends.
Characters a section's lone paragraph has at least80Less is too thin to stand alone: fold it in.

Terminal Source Discovery

The shared example reader keeps inline references separate from complete shell examples. Its terminal inventory also retains headings, fence numbers and source lines across split steps. Compact alternatives in text fences expand into branches, while shell pipes remain operators. Discovery reads source without executing commands, and reports unfinished syntax for review.

Unresolved Shell Syntax

Quoted shell values may span lines. Compound control flow, command substitutions, and shell command strings that the reader cannot model stay explicit review work rather than disappearing from discovery.

Displayed Responses

Mark a displayed response with text output in its opening fence. Its contents remain documented output, with a reported exclusion from input-command discovery, even when a Next suggestion mentions a command.

Wrapped Commands and Lookups

Use an explicit -- before the inner command in a strace example, such as strace -f -- lnk agent list; discovery retains that inner invocation. Bounded shell lookups (type -a lnk, which -a lnk, command -v lnk) are reported as introspection exclusions with their original arguments. Unsupported wrapper or lookup syntax remains a discovery problem.

Cargo Artifact Selection

Cargo's --bin lnk selects an artifact in bounded build, check, test, and clippy commands; it is reported with its arguments as an artifact-selection exclusion. A following shell command is still discovered. Unknown Cargo syntax, extra operands, or an ambiguous argument suffix remain review problems.

A Page for Each Verb

The suggested shape of a module's docs: each verb its commands start with (lnk agent move, lnk box create) has a page or folder of its own in its module's docs/, named for the verb, saying what it does and how it works with the module. The module's other pages say how its verbs connect and what the module is, as the agent module's move/, chat/ and start/ folders do.

A Suggestion, Not a Rule

The verb-pages check warns for each module, naming the verbs with no page of their own, and fails nothing. Follow it when a page reads clearer for it. A good page shared by two commands stays, and a docs tree is never reorganized for it alone.

Click Depth

How many links a reader follows from a workspace's root README to each page, the fewest there are. The report prints each workspace's average, median and deepest clicks, naming the deepest pages, and the clicks and average-clicks limits hold the workspace there.

cargo run -p link-docs-check --bin lnk-docs-clicks -- --root .

Lowering It

Link a page where a reader meets what it explains: a tool named in a task, a package named in a page's opening. A link added only to lower the number is noise. Lower the limits to what the workspace reaches, never raise them.

Documentation Prominence

Rank the documented features in one workspace using authored links and command mentions. The report reads that workspace's READMEs, English pages and action declarations, without reading case catalogues or execution history.

cargo run -p link-docs-check --bin lnk-docs-priority -- --root .
cargo run -p link-docs-check --bin lnk-docs-priority -- --root . --json

Scoring

The weights give 20 points for a feature shown on the root README, 3 per distinct outside page linking into it, 2 per page mentioning its commands and 1 per outgoing documentation target. Repeated links or mentions on one page count once. Internal links within a feature, generated inventories and generated navigation add no points.

Reviewing the Order

JSON keeps every contributing page and each feature's README examples, including their source locations and alternative branches. Navigation-only references and README link counts are separate signals. Use --weights with another file to compare opinions without changing source. Prominence is a reason to review a feature first, not measured usage, failure impact, execution time or a claim that a test has passed.

Argument Value

The default argument weights give positionals 5 points, ordinary flags 1, and required inputs 2 extra. Reviewed rules promote execution choices and permissions to 8 points, while resource selectors receive 5. The rules name their reason and can be scoped to a command. Semantic choices can earn separate value points, while incidental resource names share one input.

Marginal Value

Each source form has a floor of 1 point. A newly selected command adds 10, then its strongest new argument or unflagged default path adds its points. Default paths receive 8. Extra flags do not accumulate points without bound, and repeated command or argument coverage earns less. This is modeled value for selecting work, without claiming that any behavior was verified.

Positional Rotation

Each feature rotates through command paths and semantic positional groups before returning to flag variants of a group. Distinct connection and cloud kinds get separate turns. Free-form names of the same resource share a group. The configurable rotation applies within features, while the importance curve chooses among the eligible groups across features.

Selection Curve

The default next priority is the marginal value multiplied by the logarithms of one plus the feature points and one plus its command points, divided by the square root of one plus the feature's earlier picks. Command points use homepage presence and distinct mentioning pages. Thus agent depth gradually gives way to initial checks elsewhere. The queue suggests authoring order, with prerequisites, controls, complete workflows and timings still to resolve.