Write for an engineer who knows infrastructure tooling and is learning Rootform. Assume technical competence. Never assume Rootform knowledge. Expect familiarity with Git, shells, package managers, CI, JSON, Terraform/OpenTofu, and GitHub Releases. Explain Rootform terms before they become prerequisites.
This standard applies to documentation, CLI prose, output labels, errors, release notes, and product pages. Exact commands, identifiers, diagnostics, and machine contracts keep their defined spelling.
Public content describes the final Rootform v0.1 experience. It does not narrate development status, unpublished distribution work, the build used to generate an example, local fixtures, migration history, release machinery, or backlog. Those facts help contributors deliver the product; they do not help someone use it.
Treat documentation as a release contract. When documented behavior is not yet implemented or published, record the mismatch in an internal release checklist and block release until product and documentation agree. Do not weaken the page with a temporary disclaimer. An intentional v0.1 product limit may remain public when it changes what a user can do.
Choose the content type before deciding the structure:
Do not turn a tutorial into a concept catalog or a reference into a guided tour. Link to the content type that answers the reader's next question.
Reference tables use Description for inputs, options, outputs and exit statuses. Input and option tables also show the type and literal default. Describe the effect and essential constraints concisely; keep shared guidance outside the rows.
Apply these limits before drafting:
For every detail, ask both questions:
Does this change what the reader must do, understand, decide, expect, troubleshoot, secure, or reproduce?
Why does the reader need this information here?
If not, remove it or move it to the internal source that needs it. Technical truth alone is not a reason to publish a detail.
State prerequisites instead of teaching industry conventions. Explain product
concepts with enough depth to support a correct decision: instances and
Representations, Rules, Concepts, RF Vocabulary, Dialects, .rf.hcl, stages
and closures, Forms, Policies and Policy Packs, comparisons and
drift, locks, vendor, offline operation, and provenance. Explain what Rootform
can establish and what it refuses to invent.
Use progressive disclosure. Put the common decision first, then alternatives, then advanced or manual procedures. A simple task should remain short. A concept page can be long when its reasoning prevents a wrong conclusion.
A fact may appear on several pages, but its explanation has one owner. Match depth to context:
- a tutorial uses one sentence and a link;
- a concept page owns the mental model and boundaries;
- an authoring guide explains how to create or change it;
- a reference page defines the exact syntax and behavior.
Apply this rule to Dialects, Policies, Forms, comparisons, plans, locks, and provenance. Do not paste a full definition into every workflow. Link to a stable heading when another page owns the explanation.
A tutorial must reach its stated result from named prerequisites. A how-to must explain verification and recoverable failure at the step that can fail. An explanation must separate established facts from evidence limits. A reference must define accepted inputs, defaults and edge behavior at its generator or normative source. Keep the local consequence and a link on other pages.
Before adding a paragraph, search neighboring pages. If the same fact already has a clear home, keep only the local consequence and link. Repeated boilerplate across generated pages belongs in their shared overview.
Use one term for each external-content state. The full explanation belongs in Install, add, and vendor.
“Exact identity” names what the lock records. Reserve “pin” for digests
inside identities and “cache” for derived content under $ROOTFORM_HOME/cache.
Name the input, behavior, result, and boundary. A diagram describes the
architecture a plan or state records, not live connectivity. An indeterminate
result is not a pass. A
rootform.lock fixes selection, while --offline controls acquisition during
explicit init or vendor. Normal analysis does not acquire packages.
Use this glossary consistently:
Use architecture for stage content and Form for the complete saved result. "Rootform document" may describe a file generically, but is not a canonical object name. Name inputs as readers produce them: plan JSON for
terraform show -json plan.tfplan, saved plan for the file terraform plan -out writes, and state JSON for terraform show -json. Use
instance for a managed or data resource instance and Representation
for its entry in a stage's architecture. Keep Rule, Concept, RF Vocabulary,
Dialect, and closure consistent. --diff names the flag, not the
result. Use lowercase policy only for generic prose. Reserve backticks for
commands, paths, flags, identifiers, and literal values.
The RF Vocabulary supplies common architectural terms. A Dialect interprets provider resources using those terms. Do not describe the RF Vocabulary as a provider Dialect.
Use Rootform language in headings and navigation and the Rootform language
in prose. Keep language lowercase and omit (.rf.hcl) from the section name.
Use .rf.hcl explicitly when discussing files and syntax, including .rf.hcl files,
.rf.hcl syntax, and .rf.json.
Use Dialect for the named, versioned unit, its source, selection,
installation, and distribution. Use semantics only for architectural
meaning, evaluation behavior, semantic versions and digests, or exact public
identifiers such as the Form semantics field. Never use “semantic package,”
“selected semantics,” or similar aliases for Dialects.
In examples, put one top-level policy_pack manifest in a file at the
Policy Pack root and top-level policy declarations in .rf.hcl or .rf.json
files beneath that same root. The source root establishes ownership; Policies
need no explicit Policy Pack reference. Nested policy blocks are invalid.
Distinguish the changes a plan proposes from a comparison between two inputs, and both from the drift records a plan reports. Never describe a cross-input comparison as drift or infer a complete external-change history from the drift report. Describe relations by their declared meaning. Do not turn network context into a reachability claim or a Terraform dependency into an architecture relation. Plan evidence supports a Rule's architectural claim but is not itself the Context or Relation produced by that Rule.
Keep a Representation in a stage's architecture distinct from its presentation. A
secondary resource can be present in the Form without a permanent card in
every Explorer scene. Link to Explorer navigation
instead of calling it missing. In a comparison, indeterminate is neither no change
nor proof that the comparison failed. Link to
Comparisons.
Use present tense for behavior and imperative verbs for instructions. Prefer active voice when the actor matters. Start with the task, result, or question, not an announcement about the page.
Combine ideas that belong together. Vary sentence length according to meaning; do not replace clipped fragments with overloaded sentences. Remove a sentence that only repeats its heading, and end when the task or explanation is complete. A concrete next action is useful; a summary of the page is not.
Avoid forced symmetry, stock contrasts, and lists padded to three items. Do not
repeat sentence openings such as “Rootform does,” “You can,” or “The command”
when a natural subject is available. Use punctuation for syntax, not decoration.
The em dash character (U+2014) is forbidden in public documentation. Use a period,
comma, colon, or parentheses instead. bun run check:docs rejects this character
in authored Markdown, including headings and metadata. Avoid decorative middle
dots in technical prose.
Headings name tasks or questions. Use sentence case and stable wording so links remain useful. Put prerequisites before the first command and keep a step's expected result beside that step.
Use numbered steps when order matters, bullets for parallel facts, and tables for repeated fields or real comparisons. Do not turn every topic into a card, every section into the same three-part pattern, or conceptual prose into a sequence merely to make it look actionable.
Callouts interrupt reading, so reserve them for information whose placement or severity changes behavior:
- Warning or Caution: risk of data, security, cost, or irreversible harm;
- Important: prerequisite or constraint that can invalidate the task;
- Note: exceptional context needed at that exact point;
- Tip: optional improvement with a concrete benefit.
Ordinary explanation, product limits, and cross-links stay in prose. A callout must not rescue a weak information hierarchy or hold unrelated caveats.
Order methods by recommendation, not implementation importance. Show the recommended installer first, a platform package manager where offered, and a manual release archive as fallback. In the container panel, lead with the versioned image rather than an OS install sequence. Keep the exact commands and current alternatives in Install Rootform, their canonical user page.
Use one [ macOS | Linux | Windows | Container ] choice for primary content.
Inside a platform panel, label Recommended and Verify; add Other
options only when that platform has an alternative. Do not repeat the selected
platform as a heading. Put one Manual installation section after all panels,
visually secondary to recommended methods. Make rootform version visible
without opening manual downloads. Keep OS and CPU detection, temporary files,
archive layout, checksum production, and GitHub Release mechanics out of the
primary path. Manual verification may explain checksums when performed.
GitHub Releases can supply binary bytes without becoming the recommended installation experience. Do not expose the release pipeline merely because releases are the underlying source of the binary.
Use these examples to choose scope and wording:
Identify the shell when syntax depends on it. Do not include a prompt in a copyable command. Give file examples a filename. Separate commands from output. Name placeholders and never put an invented token or digest into an apparently runnable command.
After a command, show stable expected output or describe an observable result. Label excerpts and variable fields. Public prose does not name an internal fixture, temporary host path, or verification binary. Internal evidence records those identities and proves examples before merge.
Use synthetic infrastructure. Real customer resources, credentials, state, raw plans, private paths and private implementation material are forbidden. Synthetic plan/state exports and saved plans are allowed when they contain only deliberate public example data and their provenance is clear. They do not weaken the warning against publishing real producer inputs. Verify that the exit status supports the surrounding claim.
Use a filename on file examples and title="Command" when a command's purpose
would otherwise be unclear. Untitled output stays compact when surrounding prose
already identifies it; add a precise result label only when ambiguity remains.
Line numbers and highlights must point to something the reader needs.
Use a GitHub alert such as > [!WARNING] only under callout rules above. Public
Markdown supports framework-neutral markers:
<!-- rootform:directory -->presents orientation links;<!-- rootform:tabs Label -->groups two or more complete alternatives.
Shared instructions belong outside tabs. Link to a precise executable example when it helps; do not duplicate an entire workflow inside a neighboring page. Keep light/dark figures paired with the same state, caption, and useful alternative text.
Documentation explains tasks, models, and exact contracts at their proper depth. CLI help prioritizes command purpose, accepted input, output, and exit behavior. Interface labels name actions and use the same term as the resulting state.
Errors explain what happened, the relevant constraint, and a known next action. Quote user input only when safe. Do not invent recovery or hide an unavailable decision as success.
Marketing may explain why a capability matters, but factual claims keep the same evidence boundary. Avoid unmeasured superlatives, fake metrics, and promises beyond the v0.1 contract. Release notes describe a user-visible change and when a reader encounters it; internal refactors stay out unless they change behavior.
AI-assisted prose often repeats familiar shapes instead of answering a page's question. Treat patterns below as review prompts, never as proof of authorship:
Review layout and microcopy with prose. Aim for accuracy and natural explanation. Random variation and detector scoring do not establish editorial quality.
Read the page from a search arrival and from its navigation path. Before merging, confirm:
- The page has one clear job and gives the reader a useful next action.
- Rootform terms are explained before they become prerequisites.
- Commands and behavioral claims match the intended contract.
- Each copyable example has an observable result or a stated expected effect.
- No credentials, customer data, real plans, or private paths appear.
- A canonical page owns each definition rather than duplicating it here.
- Links and anchors work in the built site, including after heading changes.
- Code blocks and tables remain readable at narrow width.
- Prose reads naturally as text, not merely as valid Markdown structure.
Automated checks cover structure and links. Editorial review still decides whether the page is useful, accurate, and human to read.
This standard draws on the Google developer style guide, Google Technical Writing, Microsoft's writing tips, GitLab's documentation style guide, Diataxis, and the Command Line Interface Guidelines.