Tangled documentation #

The documentation is written for non-linear reading. The sidebar groups pages by what a reader is trying to do, while each page has one primary job.

Content types #

Tutorials teach a new user by completing a real task.
How-to guides help a reader accomplish a specific task.
Concept pages explain how Tangled works and how its components relate.
Operator guides cover installing and running Tangled services.
Reference pages describe exact interfaces, fields, defaults, and configuration.
Project pages record current status, recent changes, and history.

Diátaxis is a useful guide to these distinctions, not a rigid directory scheme. A task page still needs enough explanation to work when opened from search or a direct link.

The documentation homepage gives readers two initial paths: start using Tangled or understand how it works. Keep the homepage focused on those choices rather than turning it into another sidebar.

Every published article belongs in the global sidebar exactly once. Page headings belong in Starlight's page outline, not the global navigation. Order sidebar links manually so they form a useful reading path; do not rely on filename order.

Sidebar labels must make sense before a reader knows Tangled's vocabulary. Introduce the familiar role alongside a local term where necessary: Git server (knot) or CI runner (spindle) is more useful during discovery than the local name alone.

Treat published URLs and heading fragments as public interfaces. Preserve them when moving or renaming material, or add a redirect in public/_redirects.

Current behavior and history #

User documentation describes how Tangled works today. Establish behavior from code, tests, configuration, and observed interfaces. Existing documentation and blog posts are useful research material, but do not prove current behavior by themselves.

State whether behavior is current, legacy, experimental, or proposed when that distinction matters. Keep proposals out of ordinary user guidance. Blog posts remain the home for announcements and dated rationale; move durable explanations into topic-oriented documentation after checking them against the current implementation.

Use normative language only for an actual protocol, configuration, or interface contract. Otherwise describe the behavior a user can observe and rely on.

Writing style #

Lead with the behavior or relationship the page explains.
Use prose for relationships and lists for steps, fields, and genuine enumerations.
Prefer concrete services, records, commands, paths, and defaults over broad abstractions.
Avoid marketing claims, rhetorical setup, page narration, conversational filler, and repeated summaries.
Do not assume one forge's terminology is universal. Define what a feature does before comparing names or behavior.
Expand unfamiliar acronyms on first use. Prefer a plain-language role before an exact protocol term when the exact term is not yet necessary.
Give each page enough local context to work without reading the previous sidebar page.
Link to the concept needed to interpret a procedure instead of embedding an architecture guide in every task page.
Link domain names and web destinations in prose. Use code formatting for values readers should type, copy, or recognize in configuration and output.
Wrap prose at 100 columns and keep Markdown lintable.

Terms, links, and emphasis #

Formatting should tell the reader why a phrase is distinct.

Purpose	Format	Example
Define a Tangled term	Bold its first useful definition	`A spindle runs CI workflows.`
Point to an owning explanation	Use a descriptive link	`See [CI services](/spindles/).`
Name a field, value, path, or command	Use code	Set `engine` to `nixery`.
Name a visible control	Use bold	`Select Create repository.`
Name a website in prose	Use a link	`[tangled.org](https://tangled.org)`
Reuse an introduced term	Use plain text	`The spindle stores the logs.`

Bold introduces a local term; it does not mark general importance. Link when another page owns an explanation that may help the reader. Give enough local context that following the link remains optional, and do not link every later occurrence.

Do not combine bold, link, and code formatting on one phrase. Expand an unfamiliar acronym on its first use on each page, but do not repeatedly redefine familiar terms in every section.

Glossary entries #

The glossary translates Tangled and AT Protocol vocabulary rather than inventorying every noun on the site. Add an entry when a term is specific to Tangled, differs from a familiar forge concept, maps a general concept such as CI to a Tangled name, or is otherwise likely to block a reader.

Begin with the plain-language role or distinction. Follow with the exact record name, identifier shape, implementation constraint, or owning service only when that detail changes how the term is used.

Review and validation #

Review correctness before structure and voice. Before publishing:

Check commands, defaults, links, ownership boundaries, and operational consequences.
Check that each page has one primary job and that its opening establishes that job.
Open likely entry points directly and add context needed for non-linear reading.
Edit headings, terminology, and prose for a direct and natural voice.
Inspect the rendered pages at narrow and wide widths in light and dark modes.

Run the live development server with:

nix run .#watch-docs

When using a jj working copy whose files are not visible through Nix's Git source filtering, use an explicit path for the preview or build:

nix run path:.#watch-docs
nix build path:.#docs --no-link

Build the production documentation with:

nix build .#docs --no-link