Skip to content
UpRightly

Docs style guide

This page is the writing standard for /docs. Follow it for every new topic. A technical reviewer and a plain-language reviewer should both sign off before a milestone ships.

Voice

  • Write in the second person ("you"). Prefer short sentences.
  • Name the control the reader should use. Prefer "Choose Save" over "the record is persisted".
  • Explain why when a choice has a consequence (encryption, sync mode, deleting a category).
  • Use American English for v1. Keep locale-aware dates and numbers in the app; in docs, prefer ISO dates or spelled-out months.
  • Never paste help text, UI strings, icons, or branding from other finance products. Describe our screens only.

Page shape

Every feature page should include:

  1. A one-paragraph summary of what the feature is for.
  2. Numbered steps for the main task.
  3. A short "If this goes wrong" section.
  4. The minimum app version the page applies to (minAppVersion in frontmatter).
  5. A stable helpId that matches packages/help-ids.

Do not start a page with marketing copy. The marketing site already covers positioning.

Accessibility (WCAG 2.2 AA)

  • One h1 per page, then h2 / h3 in order. Do not skip levels.
  • Every image needs an alt attribute that says what the reader should learn from it, not "screenshot". Decorative images use empty alt.
  • Do not rely on color alone. If a status is red, also write the word "overdue".
  • Link text must make sense out of context. Avoid "click here".
  • Keyboard users must reach search, the version switcher, and in-page anchors.
  • Contrast stays at 4.5:1 or better. Use the shared Nuxt UI theme; do not introduce one-off colors.

Screenshots

  • Generate screenshots from this product with Playwright against seeded demo data (e2e/docs-shots). Never photograph another product.
  • Never include a real household, bank login, or personal file path.
  • Store images under docs/user/images/ and reference them with descriptive alt text.
  • M0 has no screenshots yet. Do not add placeholder images.

Search and versioning

  • Put the words a reader would type into the first paragraph ("reconcile", "private sync", "import CSV").
  • Each release is a git tag. The site will publish /docs/latest and /docs/vX.Y with a version switcher. M0 only publishes latest.
  • The desktop app bundles the docs for its own version and opens them offline.

Help-ids

In-app "?" controls look up an id such as docs.getting-started, never a raw URL. Add every new id to packages/help-ids and point it at a file in docs/user. CI runs pnpm docs:check and fails if a target file is missing.

What we do not document yet

Foundations (M0) only publishes this style guide and Getting started. Feature pages for the register, budgets, investments, and sync are required exit criteria of later milestones, not of this one.