Electron Stagewright docs

ADR-013: Public documentation layout

Status: Accepted.

Context

The repository's docs/ directory began life as a private workspace and is gitignored as a whole (docs/*). When the Architecture Decision Records became public, docs/adr/ was re-included via a gitignore negation rather than moved, keeping the conventional path. The generated tool reference predates that exception: it was placed at the repository root (TOOL-REFERENCE.md) precisely because nothing under docs/ could be tracked at the time.

User-facing guides (a getting-started tutorial, task-oriented how-tos, a migration guide) now need a public home. Three layouts were on the table: more root-level files, a new top-level directory, or further re-includes under docs/.

Decision

Public documentation lives under docs/, re-included directory by directory through explicit gitignore negations:

Two rules keep this layout safe and legible:

  1. Each re-included directory is wholly public. Nothing private may be placed inside a re-included directory, and a tracked file must never link to a path outside the re-included set (the rest of docs/ is local-only and would 404 for everyone else). A repository test enforces the link rule mechanically.
  2. The repository root keeps exactly two documentation artifacts: README.md (the landing page) and the generated TOOL-REFERENCE.md. The tool reference stays at the root rather than moving under docs/ — it is the most linked-to artifact and link stability outweighs tidiness.

Alternatives considered

Consequences

Status Update — 2026-06-14

The guides directory is now organized internally by the four Diátaxis modes, so each page has one job and a reader can tell which from its type:

The guides index (docs/guides/README.md) labels these four modes explicitly, and each how-to closes with a pointer up to concepts.md. This refines how the docs/guides/ directory is organized; the layout decision above — public docs re-included directory by directory, the root holding only README.md and TOOL-REFERENCE.md — is unchanged.

Status Update — 2026-06-15

The static-site pipeline the "Alternatives" section anticipated — "a static-site pipeline can consume docs/adr/ + docs/guides/ later without moving anything" — is now implemented, and nothing was moved.