# Design a technical reference

An engineer needs to find an answer, distinguish running behavior from proposals,
and follow the path into code or operational detail. Let the system's information
architecture determine the page, not a general productivity dashboard.

Keep frequent actions and focused view tabs within reach. Organize technical
knowledge by topic with clear headings; do not add a sprint schedule to a wiki
unless it is part of the requested workflow.

## Write for the people using the docs

Use the system’s name and specific destinations such as “Getting started,”
“Architecture,” “Runbooks,” and “Proposals.” For a release overview, name charts
for what they measure, such as “Work by status”; do not imply a readiness score
from task counts. Prefer “Document status” to “Maturity” when introducing a new
property, while keeping established team terminology and exact technical names.
Retain useful terms such as “runbook” for an engineering audience. Explain an
unfamiliar acronym on first use; do not simplify commands, identifiers, or code.
Keep instructions concrete: “Open the blocked issue,” not “Inspect the linked
record.”

## Make a navigable manual

Use the system name and a concise statement of its purpose. Lead with a topic
index or compact document list, grouped by the questions engineers ask: setup,
architecture, operations, proposals. A table of contents and continuous reference
page can serve a small system better than a card gallery.

Use one readable main column for technical explanations. A navigation rail is
useful for a large library; paired summary panels are not required. Treat code,
configuration, diagrams, and commands as primary content when supplied. Keep
exact commands and code intact. Never invent runnable commands or architecture
components to fill a visual layout.

Show current architecture and proposals as separate states in navigation as well
as document bodies. Put tradeoffs and unanswered questions in the proposal; do
not repeat them as a decorative warning on every section. Keep operational steps
short and sequential with actual links to dashboards and escalation routes.

A restrained technical style can use rules, compact headings, and monospace for
code or identifiers. If a page-level font is supported, choose for readability;
monospace is not compulsory for prose. Avoid motivational copy, arbitrary icon
cards, or a content calendar imported from another domain.

## Judge the result

Find the setup route, open the current architecture, and locate an unapproved
proposal. Check maturity labels and exact technical content. The home should be
useful even after removing its title and icon; topic structure must identify its
purpose. Inspect long lines, tables, and code at available widths. State honestly
when rendering or an external link could not be checked.

Choose density and navigation for technical reading. Do not assume a parent
determines or prevents a page's layout.
