For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /packs/shared/documentation/writing.md.
Quick start

Writing

Start with the question the page answers. Put the answer ahead of the history behind it.

Purpose and placement

Why

A contributor changing file selection needs a contract, while a new user needs an installation guide. Keeping those purposes distinct prevents a product page from becoming a second standards source.

PurposeHomeShape
Product pitch and statusRoot READMEValue, working capabilities, and a development starting point
Engineering rulesOwning standards componentTopic, rationale, normative rules, and a useful example
Contributor taskcontributing/guides/Prerequisites, numbered steps, and a verification result
Product explanationdocs/concepts/Purpose, design reasoning, and decided or open behavior
Package-specific referenceOwning package's docs/Caller-facing contracts, fields, and outcomes
Disposable planningGitignored .scratchpad/Notes limited to the current task

Rules

  • MUST choose the table's location and page shape from the reader's task. [review]
  • MUST keep each authoritative rule in its owning component and route readers to it wherever other pages need it. [review]
  • MUST label implemented behavior, future work, and illustrative examples distinctly. [review]
  • MUST keep each standards section on one topic with ### Why and ### Rules subsections. [review]
  • MUST limit the rationale to one or two concrete sentences. [review]
  • MUST use uppercase RFC 2119 terms when a sentence states a normative requirement. [review]
  • MUST add a new standard to the pack's reading index. [review]
  • MUST describe generators, websites, index synchronization, and CLI capabilities only when they actually exist. [review]

[review]

Granary's component-content tests check standard metadata and rationale/rules/enforcement headings. Review checks page purpose, canonical ownership, and concise normative language.

Voice

Why

Contributor guidance should tell a reader what to do on this repository. Promotional wording obscures that instruction.

Rules

  • MUST prefer short declarative sentences, sentence-case headings, and names of real operations or files. [review]
  • MUST remove filler, exaggerated claims, corporate comparisons, and content-free conclusions. [review]
  • MUST reserve decorative emojis for an explicit user request. [review]
  • MAY use the established product voice in the root README while keeping standards prescriptive. [review]

Use Formatting for metadata, links, fences, and punctuation.

[review]

Granary's component-content tests check standard metadata and rationale/rules/enforcement headings. Review checks page purpose, canonical ownership, and concise normative language.

Enforcement

Granary's component-content tests check standard metadata and rationale/rules/enforcement headings. Review checks page purpose, canonical ownership, and concise normative language.