~ knotless Search/
↑↓ move↵ open⇧↵ all results

chadtmiller.com/hud

A remote MCP server that shows atproto records as interactive UI inside MCP Apps hosts

0
0
225 lines · 13.9 KB Raw History

HUD docs: style guide

Not a page (files starting with _ aren't pages). Read this before writing or editing one. It's marco's guide (https://github.com/jazware/marco/blob/main/docs/_style.md), itself vlRelay's and vlpds's, cut down to what HUD's docs use. HUD has no docs renderer, so pages are plain Markdown, read on knotless and in an editor.

It covers README.md and the pages in docs/. AGENTS.md, code comments, lexicon descriptions and tool text keep their own style.

Where things go

  • README.md says what HUD is, how to run it and where each page is. Nothing else.
  • docs/<slug>.md is one page per topic. Each fact has one home page. Other pages state it in a clause and link there.
  • When the code changes a default or a mechanism, update the page that owns it in the same change.
PageOwns
overview.mdwhat HUD is, its parts, what isn't built
tools.mdthe MCP tools, their inputs and results, query, the writes
views.mdviews: joins, summaries, layouts, query joins, the bundled views, the operator's views (HUD_APPS), trust, profile sections, records, launch
app-pages.mdapp pages and where an account opens
knotless.mdknotless's views and how its queries are made
sign-in.mdsign-in, feed interactions, saved feeds, chats, procedures
workspace.mdthe workspace: canvases, tiles, agents, music, themes, where canvases live
playground.mdthe playground: writing a view beside what it draws, sharing it
sdk.mdthe packages an app is built on, their registries, HUD's version, releasing
running.mdrunning HUD: commands, environment variables, the image
memory.mdwhat HUD holds in memory and how to measure it
observability.mdwhat HUD logs, its traces and metrics, the lines it keeps for its operators, how to read them
workspace-api.mdthe workspace's XRPC methods, its event stream, /icon
internals.mdhow it works: identity, lexicons, blobs, joins, counts, queries, storage, checks

node harness/docs.mjs (in just lint) checks every page: its front matter, no # heading, every link to a page or heading that exists, and the punctuation rules below in prose.

Current version only

The pages document the HUD that's in the tree, nothing earlier.

  • No history: no "used to", "no longer", "was changed", "now does", "originally", and no comparison with an earlier HUD. Migration of old data (canvases from before columns) is current behaviour and stays, stated as what HUD does with such data today.
  • No design iterations or rejected alternatives. If a page needs the reasoning, give the current reason in one sentence.
  • Say what isn't built. If something is missing (views published as records), say so plainly.

Adding a page

  1. Create docs/<slug>.md with front matter:

    ---
    title: Views                   # the page's title
    section: HUD                   # "HUD", "Operations" or "Reference"
    order: 3                       # position in its section (HUD 1-99, Operations 100+, Reference 300+); unique
    summary: "One sentence under the title. Quote it if it contains ': '."
    ---
    
  2. Start the body with one or two short paragraphs, then ## sections. No # heading: the title comes from front matter.

  3. Link to other pages by file: [the workspace's methods](workspace-api.md), [query joins](views.md#query-joins). Anchors are the heading text, lowercased, with spaces turned into - and other punctuation dropped (GitHub's rule).

  4. Add it to the table above and to the README's list.

  5. Run node harness/docs.mjs.

Page shape

  1. One or two short paragraphs saying what the thing is and why a reader cares. Not a table of contents for the page: the headings already do that.
  2. Sections (##, ### under them), each opening with its table, steps or example when the idea has a shape, then the explanation.
  3. Links out at the end of a section ("Details: …") rather than repeating another page.

overview.md is the worked example.

Tone and content

  • Reader-focused. Write for someone running HUD, connecting a host to it, writing a view or working on its code: what it does, what it costs, what to watch, what to do.
  • Concise. Short sentences, plain words, active voice. Lead with the point. Voice spells out what that means sentence by sentence.
  • Numbers with their basis: "a 695 KB avatar is 6 KB as its thumbnail". Say whether a number is measured, a limit or a default.
  • Defaults with their variable or flag: "64 MiB by default (HUD_CACHE_MEMORY_BYTES)". Name methods, fields and files exactly.
  • Code paths sparingly, as inline code (hud_core::canvas::store), when a reader would actually go read it.
  • Callouts: > [!NOTE], > [!TIP], > [!WARNING], > [!DANGER] as the first line of a blockquote. Use them rarely. One warning on a page reads as a warning, but five read as noise.

Voice

The docs should read like the author explaining the system to another engineer, tightened for reference docs. Most of what makes docs slow to read comes from a handful of habits that a language model reaches for and a person explaining doesn't. This section lists them so they can be checked for.

What the voice is

  • Plain declarative sentences, one idea each. Most sentences run 12-25 words. No semicolons and no em dashes in prose.
  • Conversational connectives. Sentences link up with "So", "Since", "Now", "That means", "Additionally", "In this case", "That being said". They don't link up with punctuation.
  • Contractions everywhere. it's, don't, can't, isn't, there's, that's, we'd, won't.
  • Person. The operator, or the person using HUD, is "you" ("If you run HUD behind a proxy…"). The system is the subject of mechanism sentences ("HUD checks…", "The proxy fetches…", "A view names…"). "We" is fine when walking the reader through a mechanism or a calculation. No "I".
  • Concrete before abstract. Name the problem or the scenario, then the mechanism. "A gallery is three collections" lands faster than "records relate across collections". When a term needs a definition, give it in one plain sentence ("An app is the domain behind an NSID") and then an example.
  • Numbers do the arguing. Round numbers with ~ and units, and the arithmetic when it explains a cost. One "about" or "~" per number is enough.
  • Trade-offs said plainly. State the cost, give the number, say why it's acceptable. No hand-wringing and no stacked hedges.
  • Paragraphs of 1-4 sentences. Short is good. What's banned is a short paragraph whose only job is to land a line for effect (see the list below).
  • Parentheses for asides, not dashes or semicolons: "(the default)", "(HUD_SPACES)", "(a like, a repost)". Keep them short and useful: a flag, a default, a basis, an example.
  • Humour is rare. At most one light aside on a page, and never in the Operations pages.
  • Words the voice uses: keep up with, get by on, a bit, pretty, just (sparingly), cheap, plenty, hold up, spread out, so, since, that's, around, something like.

Banned patterns

Search for each of these on every page you touch.

PatternLooks likeDo instead
Semicolon splice"Slots are permanent; shards are not."Two sentences, or join with "and", "but" or "so".
Em dash or -- aside"the log — and only the log — is durable"Parentheses, a comma, or a second sentence.
"X, not Y" / "not X, but Y" flourish"Logins use the CPU, not commits."Say X. Mention Y only if readers would assume it, in its own sentence.
Colon chains"The rule is simple: one owner per shard: always." / "A: B, C: D"One colon per sentence at most, and only to introduce a list, a code span or an example.
Rule-of-three lists"fast, cheap and simple"Keep the items that carry information. Two is fine. One is often better.
Abstract nouns for actions"the persistence of", "guarantees around", "the handling of"Use the verb: "stores", "makes sure", "handles".
Filler and AI-ismsload-bearing, crucially, critically, importantly, in practice, it's worth noting, notably, essentially, effectively (as filler), robust, seamless(ly), under the hood, the heart of, first-class, by design, key (as in "the key insight"), "this is where X comes in", "the trick is", "the catch is"Delete the word. If the sentence falls apart, rewrite it.
Bold lead-in on every bullet"- Fail-stop over guessing. When a node…"Plain bullets. Bold only a term at its definition, or a real warning. Reference lists of named things (components, variables, methods) can start with the name in code or plain text and a period.
Bold for emphasis in running text"the PDS is the database"No bold. If a phrase matters, put it first in the sentence.
One-line paragraph for drama"Unavailability is recoverable; a forked repo is not." on its ownFold it into the paragraph it concludes, as a normal sentence.
Aphorism endings"Less to write and less that can disagree."State the consequence plainly or cut it.
Over-precise parentheticals"(at the default 10 s, 12 s in tests, see below)"One fact per parenthesis. Move the rest to the section or table that owns it.
Narrating the page"This page covers…" / "The short version:" / "In this section we'll look at"Delete. Start with the content. A one-line pointer to another page for a related topic is fine.
Stacked qualifiers"typically only briefly and usually safely", "about ~"One qualifier, or none if the number already has ~.
Sentence fragments as style"Nothing else." / "By design."Full sentences in the pages.
Italic stress"only decides when"Rewrite so the stressed word is at the end of the sentence.
Restating the obvious"This matters because…" before something that obviously mattersCut the lead-in, keep the reason.
Exclamation marks"and it's free!"None in the docs.
Possessive chains"its query's lexicon's main def's params" / "each its icon, its name"Name the thing and use a verb: "the params of the main def in the query's lexicon", "each with its icon and name".

Mechanical pass

Apply these in order to every paragraph, list item and table cell you edit.

  1. Replace every semicolon in prose with a period or with "and", "but" or "so". Table cells may use · to separate short items instead.
  2. Replace every em dash or double hyphen used as punctuation.
  3. Count colons. More than one in a sentence: split it. A colon that isn't introducing a list, code or an example: make it a period or "because"/"so".
  4. Find ", not " and "rather than". Keep one only when it corrects a real misconception. Otherwise drop the contrast half.
  5. Delete every word in the filler list. Re-read the sentence.
  6. Remove bold except (a) a term at its definition, once per page, and (b) callouts. Remove bold lead-ins from bullets that are prose. Remove italics used for stress.
  7. Use contractions: it is → it's, does not → doesn't, cannot → can't, there is → there's.
  8. Split any sentence over ~35 words, or with more than two clauses joined by commas.
  9. Make the actor the subject: "is checked by the server" → "the server checks".
  10. Delete sentences that describe the page or section instead of the system.
  11. Turn lists of three into lists of what's needed.
  12. Read the paragraph aloud. If you wouldn't say it to a coworker, rewrite it.

Length usually comes out about the same. Splitting crammed sentences and adding connectives costs a few words, and cutting flourish wins them back. The goal is faster reading, not a lower word count.

Before and after

From HUD's README, rewritten in the voice:

Before: Made with no sign-in, a call is made as no one: public data only, and a query that needs an account (getTimeline) asks the host to sign in.

After: Without sign-in, HUD makes the call as no one, so it only reads public data. A query that needs an account (getTimeline) asks the host to sign in.

Before: A record that cannot be read is a null or skipped result, never an error.

After: If a record can't be read, its result is null or skipped, and the call still answers.

Before: Identity: a handle's DID from DNS (_atproto.<handle>, asked of a public resolver) or https://<handle>/.well-known/atproto-did; the DID's document from PLC or did:web; its PDS from #atproto_pds.

After: HUD finds a handle's DID through DNS (_atproto.<handle>, asked of a public resolver) or at https://<handle>/.well-known/atproto-did. It reads the DID's document from PLC or did:web, and the PDS from its #atproto_pds service.

The Operations pages

The Operations pages (running.md, memory.md) are read by someone running HUD, sometimes in a hurry. They're terser than the other pages, and imperative where they say what to do.

  • Every command in backticks, runnable as written. Every limit with its number and variable.
  • Explain a mechanism only as far as it changes what to do, and link the page that owns it.
  • No humour.

What must not change

A voice pass changes wording only. Check each of these before committing:

  • Facts. Every number, unit, default, variable, method, field, path, error name and limit stays exactly as it is. If a sentence goes, the fact in it moves to another sentence or was already stated on the page.
  • Nothing new. Don't add a claim, number, feature or promise that isn't already in the page or the code. The docs only describe what exists. If something reads wrong, flag it instead of fixing it in prose.
  • Headings. harness/docs.mjs checks every link and anchor. If a heading must change, update every link to it in the same commit.
  • Links. Every link stays and points to the same target.
  • Front matter. title, section and order stay. summary may be reworded for voice (keep it quoted if it contains : ).
  • Code blocks and inline code are untouched.
  • Callouts stay callouts, with the same level.