Documentation Guide

June 14, 2026 ยท View on GitHub

This guide defines where documentation should live and how new documentation files should be named.

The goal is discoverability: a new contributor should be able to start from docs/README.md, then follow a predictable location and naming scheme.

Placement Rules

Use the closest stable owner:

  • Repository-wide user or contributor entry points stay at the repository root.
  • Project-wide architecture and process docs live under docs/.
  • Code-owner guides live near the code they describe:
    • src/README.md for frontend implementation guidance.
    • src-tauri/README.md for the Tauri app crate.
    • core/README.md for hardviz-core.
  • Task guides that cross code owners live under docs/development/.
  • User-facing guides that are published by the website live under docs/user/.
  • Architecture docs live under docs/architecture/.
  • Release, verification, signing, and distribution docs should live under docs/release/ or docs/security/ when those directories are introduced.
  • Generated legal/license notices currently live under docs/third-party-notices/.

Naming Rules

For new documentation:

  • Use lowercase kebab-case directory names.
  • Use lowercase kebab-case Markdown filenames.
  • Use .ja.md for Japanese translations of the same document.
  • Generated or externally conventional files may keep their required names, for example THIRD_PARTY_NOTICES.md.
  • Keep root convention filenames uppercase where tools expect them: README.md, CONTRIBUTING.md, SECURITY.md, LICENSE.

Examples:

docs/architecture/backend.md
docs/development/add-language.md
docs/download-verification.md
docs/download-verification.ja.md

Existing Exceptions

The repository still contains a few naming exceptions:

  • docs/third-party-notices/*/THIRD_PARTY_NOTICES.md
  • tmp/THIRD_PARTY_NOTICES.md
  • root-level GitHub convention files such as README.md, CONTRIBUTING.md, and SECURITY.md

Do not rename these opportunistically in unrelated changes. Some are linked from existing docs, generated by workflows, or consumed by Tauri bundling.

When renaming one of these paths, update all references in the same change:

  • Markdown links.
  • .github/workflows/**.
  • .github/scripts/**.
  • Tauri configuration under src-tauri/**.
  • Any frontend/backend code that loads the file at runtime.

Third-Party Notices

docs/third-party-notices/ stores generated platform notices and manual notice fragments. This is documentation/legal output, so it belongs under docs/.

tmp/THIRD_PARTY_NOTICES.md is different: it is currently the bundled runtime resource used by Tauri. It should not be deleted just because it lives under tmp/.

Adding New Docs

Before adding a new document:

  1. Check docs/README.md for an existing location.
  2. Prefer adding a short index link if the document should be discoverable.
  3. Keep task guides focused on one workflow.
  4. Keep architecture docs descriptive rather than step-by-step.
  5. Avoid duplicating detailed file trees in multiple places unless the tree is stable and useful for that document's audience.