Documentation Meta#

This page is the source of truth for how this repository writes and maintains documentation.

Source of truth and structure#

Docs source lives under docs/ as .rst files.
Keep the toctree structure coherent across:
- docs/how-to/
- docs/explanation/
- docs/reference/
Do not hand-edit generated output under docs/_build/.
Under docs/reference/project/, keep index.rst, changelog.rst, and plan.rst maintained.
Keep project changelog entries concise with 3-5 word summaries and links to dated files.

Only changelog pages describe what changed, what was removed, or how behavior used to work.
Changelog pages may use past tense when they record project history.
How-to, explanation, and reference pages describe the current behavior only.
When behavior changes, describe the current behavior and link the relevant changelog entry instead of describing the older behavior.

Prefer task-first runbook style: show runnable commands first, then short context.
Keep pages concise and scannable: short sections, direct headings, minimal prose.
Include operational guardrails explicitly, such as dry-run vs destructive behavior and branch or worktree preconditions.
Include practical defaults and real-world usage notes when they affect command choice.
For CLI reference pages, prefer generated command output snapshots under docs/generated/ and include them with literalinclude.
Exclude non-essential narrative, long rationale, abstract architecture, and generic commentary from how-to and reference pages.

Use dated filename format YYYY-MM-mmm-<slug>.rst.
In docs/reference/project/changelog.rst, visible labels use month-key style YYYY-MM-mmm - ....
In docs/reference/project/changelog.rst, keep sections in reverse chronological order: newest year first, then older years.
Within each year section, insert new entries at the top so newer month-key entries appear before older ones.
In each dated changelog page:
- The title stays YYYY-MM mmm - <summary>.
- The first subsection heading is YYYY-MM-DD - Day.
- Immediately after that heading, add exactly one plain sentence line.
- Use section heading Change summary.
- Use :ref: links to connect changelog entries to explanation pages and explanation pages back to changelog entries.
Changelog entries are historical artifacts. When removing large code or doc sections, do not delete or rewrite historical changelog summaries.
If a changelog :ref: target is removed, keep the historical mention and replace only the broken :ref: item with plain text under Related docs. Use a code-block:: text list of removed doc paths.

Write explanation pages as operational runbooks for maintainers.

Required style:

Prefer procedural wording with verbs like loads, sources, includes, and resolves.
Use present tense to describe behavior.
Focus on runtime behavior and include order, not abstract architecture claims.
Do not over-explain. Keep explanation pages lean and focused on how the config works.
Prefer plain, non-technical language. Use technical terms only when they name a file, command, API, setting, or behavior the reader needs.
Remove non-essential narrative, long rationale, and repeated path explanations.
Keep sections compact and scannable. Use lists when they read better than paragraphs.
Keep list formatting consistent. Add one blank line between numbered lists and bullet lists.
Use short, explicit bullets.
Replace vague shorthand with concrete behavior. State what the code loads, skips, compares, or writes, and why that step exists.
When introducing a code-specific term, define it in the same section or rephrase it in plain language.

Do not:

Repeat full relative paths in bullets when the path already appears in a file tree.
Add broad statements that cannot be verified from config files.
Keep sections that do not help a maintainer trace behavior.
Copy large code blocks into explanation pages when the surrounding text does not add useful context.

For module pages such as file navigation, Treesitter, and LSP, use this order unless a tool-specific exception is requested:

Omit sections that only duplicate code, restate nearby bullets, or add no clear payoff for the reader.

When documenting source or include edges, use literalinclude snippets from actual config files.

Each such snippet must include:

Additional rules:

Preserve the current explanation-page layout workflow for tool pages.

Tree layout section rules:

Use heading Directory layout, Overall structure, or Logical flow as appropriate.
Keep this section layout-only. Do not add explanatory prose under the heading.
Wrap the layout include in a sphinx-design dropdown.
The dropdown label is exactly Show layout.
Use generated layout files from docs/generated/ when they are available.
For generated layout includes, use :caption: with the relative config directory path.
Render generated layout includes with :language: sh.

Sphinx-generated layout implementation rules:

Implement layout generation in Sphinx hooks within docs/conf.py.
Generate snapshots into docs/generated/.
Command preference order is:
1. lsd --almost-all --tree
2. tree
3. ls -al <config-dir>/*
Resolve the available tool choice once per build when possible.
Write generated files only when content changes to prevent live-reload loops.
Keep generated layout artifact extension as .txt.