Skip to content

documentation-guide.md

Latest commit

 

History

History
120 lines (93 loc) · 4.97 KB

documentation-guide.md

File metadata and controls

120 lines (93 loc) · 4.97 KB
Raw

Documentation Guide

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.

Documentation Depth

Treat code as the living specification. Make behavior and constraints readable through names, types, responsibility boundaries and focused tests. Detailed prose that restates the implementation drifts as code changes; keep rationale and trade-offs that cannot be understood from code in documentation.

HardwareVisualizer does not use specification-driven development. Do not maintain a parallel, detailed behavioral specification or add a specification-approval workflow.

Design Docs explain the problem, chosen approach, meaningful alternatives, trade-offs, ownership boundaries and remaining decisions. Keep them as short as those decisions allow. When a database or library owns an algorithm, document why it was selected and its application-level consequences; do not duplicate its internal algorithm. Keep detailed measurement procedures in benchmark code and raw evidence, with a short results summary in the Design Doc. ADRs preserve architecturally significant decisions and their reasons.

Clean-room sensor work has separate requirements for implementation-ready reference specifications, source provenance and role separation. Those scoped requirements remain mandatory; they support independent implementation and do not mean that the project adopts specification-driven development.

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/.
  • Cross-cutting product and engineering direction lives in docs/design-principles.md.
  • AI learning provenance lives under docs/agents/. Promote durable rules to their real owner rather than treating the learning record as canonical.
  • Shared agent path rules live under .agents/rules/. GitHub-specific files under .github/ should remain configuration, workflow, template, or integration artifacts rather than the primary home for agent-neutral rules.
  • 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/.
  • Design Docs explaining proposed structures, evaluated alternatives and trade-offs live under docs/design/.
  • Current 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/licenses/.

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/licenses/*/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/licenses/ stores license information (LICENSE_INFORMATION.md, MIT-pre-relicense.txt) plus generated per-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.