Writing Docs

Docs are for someone who wants to use the thing now. Judge every page by how fast they get there.

  • One set of docs. Every fact is in a folder's docs/en/, and every file there is a page on www.local.link: nothing is said only in the repository or only on the website. A README.md outside docs/ (this folder's, .github/'s) holds no information: the name, its page, and links into the docs. A part's pages change in the PR that changes its code, in the folder that holds it; a link to another folder's page goes to it on https://www.local.link. The rules, and how the website reads every folder: the website's page.

  • Read it a level at a time. A reader skims the site from the top: the home page's first paragraph, then each tab's, then each page's, then each page's headings and the first sentence under each. Each of those levels, read alone, is a true and whole picture, and adds to the one above without repeating it. So a page's first paragraph is at most two sentences, saying what the reader gets. A heading names the task, so the sentence under it adds what the heading can't: the result, a condition or a cost. It never restates the heading, and a section whose heading and commands say it all needs none ("Stop it", "Troubleshooting"). Detail never comes before the point: a sentence that changes the picture at no level goes down, to --help, a spec, Decisions or Security, or goes. node scripts/skim.mjs in link-web prints the levels, with their words.

    Before: "lnk-openclaw lets a Link agent run on OpenClaw, the personal AI assistant. It answers Link's harness adapter commands: installing OpenClaw, configuring it, and saying how to run it."

    After: "OpenClaw, the personal AI assistant, run for you: Link installs it, keeps it in a sandbox and keeps it up to date."

  • A person's voice. Write as you'd explain it to a colleague at a desk: whole sentences with their articles, one idea each. At most one colon in a paragraph, no semicolons between clauses, and no parentheses inside parentheses. Say "never", "only" or "at most" when the limit is the point, not by habit. A list is for three or more like things, and a bold lead-in only where a reader scans for it.

    Before: "Needs: macOS or Linux, the tunnel plugin (lnk up tunnels, which adds the accounts plugin for your login) and a GitHub account on Local Link's invite list. It's free."

    After: "You need a Mac or Linux, and a GitHub account on Local Link's invite list. lnk up tunnels adds what it needs. It's free."

  • A tab's page sells first. The home page, and each tab's own page (Agents, Harnesses, Models, Machines, Architecture, More), is the pitch to a developer deciding whether to use it: what it's for, in a sentence, then its three to five ideas, each a line that links to where it's explained, then its quickstart. What it needs comes after, in ## What it needs, never above the pitch. The site is a tree of such ideas: the home page's lead to the tabs, a tab's to the pages under it (link-web/docs/en/website.md's ## Tabs).

  • Commands first. A page's first screen is how to do its job: commands to copy, each with a short comment. Explanation comes after, and only as much as someone needs to use it. A comment goes after an lnk command only, which drops it: zsh, the Mac's shell, passes it on as arguments. Another program's comment goes on the line above.

  • One page, one job. A feature page (docs/en/<tab>/<part>, which the website shows at /<tab>/<part>) is a quickstart and one short section per task, titled as the task ("Switch harnesses", "Remove a harness"), with its commands and the flags that matter to it. Reference (every field of a --json output, every setting, every file) goes on its own page, opened only when needed.

  • Short. Never a dump of the help: every flag is in lnk <group> <command> --help. Never a map of the code: read the code. Say a thing once, in the one place it belongs, and link to it elsewhere.

  • Checked. Run every command a doc gives before it's merged. A wrong command is worse than none. cargo test checks that links and anchors resolve and that each lnk <group> <command> exists, in a code block or in inline code (src/tests/e2e/tests/docs.rs); flags and what a command does are yours to run.

  • Titles and names in Title Case, and the same everywhere. A page's # title is what the site's tree calls it, so it's short and says what the page is beside its siblings: a part's security page is # Security, its decisions # Decisions, and its README, the first page of its section, # Get Started. A tab's own page is the exception: the tree calls it Get Started, and its # title is a short tagline written as a sentence, as the home page's is ("An AI that answers only you"), so each tab says something of its own. A link that names a page calls it by its title (Security). The names of Link's parts keep their capitals wherever they're written: Link Harness, Link Memory, Link Scheduler, Hermes Agent. ## headings are tasks, in sentence case ("Switch harnesses").

  • Ten at most. No heading has more than ten headings under it: ten ## on a page, ten ### under a ##. Group a longer list under headings one level deeper, and keep the old headings' words, so links to them still work. The site's tree holds ten pages under a page at most, too.

  • Names: "Link" is the command line and its plugins ("Link's bucket plugin", "Link Harness", "Link Memory"). "Local Link" is the company, the product, the website, the repository, the relay it runs, and what it's for. The command is lnk, never "LNK".

  • Plain sentences. The verb near the front, no stacked parentheses. Say up front what a task needs: which OS, plugins, accounts, and whether it costs money; on a tab's page, right after its quickstart.

  • Tables only for short lookups of like things (symptom and fix, variable and default): a few words per cell, never a paragraph, never a table that only points at files.

  • Why goes in decisions.md beside the doc it explains (docs/en/machines/boxes/decisions.md, docs/en/more/developing/decisions.md, ...): one heading per decision, as the question, grouped under ## topics when there are more than ten, and a short paragraph in the present tense saying what was decided and why. The doc itself links to it once, at the end.

  • QA: a docs/en/more/developing/run/qa/ page is steps to repeat, in the same style: what it needs, the commands, and what you see when it works. No dates, ticks or findings, but the one line per part in its README.md saying when it last passed, and on what. A check a script can do is in the script, and the page runs it.

  • Security: each part's guarantees, limits and gaps are its security.md beside its page, in the same plain style; what spans parts (who is trusted, privacy and logs, known limitations) is docs/en/architecture/security.md; how to report a vulnerability is docs/en/more/vulnerabilities.md. The feature page links to its security.md once, rather than repeating it.