documentation hygiene

Documentation Community

Skill notes

Overview

Define the project's documentation contract — what gets documented, where it lives, how it stays current — before docs rot. Output is .forge/docs-policy.md: README standard per repo and subdirectory, in-code comment policy (WHY not WHAT), doc-rot prevention rules (dates, code links, generated docs), public-vs-internal doc split, and changelog discipline. Pairs with code-review-and-quality (review enforces the policy) and shipping-and-launch (CHANGELOG updated per release).

When to Use

A repo is older than 3 months and the README hasn't been touched since the first commit Subdirectories have grown to 5+ files with no entry-point doc In-code comments are mostly restating the code instead of explaining intent A new contributor takes >2 hours to figure out where things live A release shipped without a CHANGELOG entry

When NOT to Use

Greenfield project, day one — README will exist; full policy can wait until week 2 Throwaway prototype A single typo fix in one doc

Common Rationalizations

Thought · Reality "The code is self-documenting" · Code shows what, not why. Two months later the original author cannot reconstruct why. "Docs get stale anyway, why bother" · Dated docs with code links rot slower than undated docs. The half-life of a comment near its code is years; far from its code, weeks. "README is enough" · README without subdirectory docs creates a treasure hunt for every new contributor.

Red Flags

A README that hasn't been touched since the repo was created A subdirectory with 10+ files and no entry-point doc A comment that restates the code: // increment i by 1 next to i++ A doc with no last-updated date or commit reference A dead link in any doc (broken internal link or 404 external)

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
Domain
Documentation
Author-declared agents
No explicit declaration found; this is not inferred or tested compatibility
Static check
88 / 100 · heuristic scan, not runtime safety proof
Runtime evidence
Not run; no isolated runtime test evidence is currently recorded
Author / version / license
@tomevault-io · no license declared
Token usage
Lean
Setup complexity
Plug-and-play
External API key
Not required
Operating systems
Unspecified (assume cross-platform)
Runtime requirements
No explicit requirements detected
Detected file/system behavior
  • Read-only
  • Write / modify
Network behavior
Local-only
Install commands
None (reference only)

Heads up: Tool permissions are not declared; actual access depends on the runtime.

01
Step 1: Define the README standard

In `.forge/docs-policy.md`, the README contract for every repo top-level: For every subdirectory with >5 files: a README that answers "what is in here, why is it here, who owns it."

02
Step 2: Set the in-code comment policy

The rule: explain WHY, not WHAT. Bad (WHAT) · Good (WHY) `// increment i` · `// skip the sentinel row at index 0` `// loop over users` · `// fan-out concurrency capped at 5 to respect upstream rate limit` `// returns null` · `// returns null when the user has been soft-deleted; callers must filter`

03
Step 3: Establish doc-rot prevention

Every doc carries: Last-updated date at the top (or a `` footer) Code links that resolve at HEAD (use permalinks to `main`, not commit hashes) — if the link 404s, CI fails A scope statement — what this doc covers, what it doesn't An owner — a person or team responsible for keeping it current

04
Step 4: Define the public-vs-internal doc split

In `.forge/docs-policy.md`: Public docs — user-facing, marketing-grade, versioned (cross-ref `api-design` for endpoint docs) Internal docs — engineering-facing, in-repo, allowed to assume context (`CONTRIBUTING.md`, ADRs, runbooks) Confidential docs — credentials, customer data, financials — never in the repo Each doc has a banner indicating its tier.

05
Step 5: Set changelog discipline

Follow Keep a Changelog: one entry per user-visible change, grouped by `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`. Breaking changes flagged with `BREAKING:` prefix. Refactors don't get entries unless they affect performance, security, or behavior. Updated *in the PR that makes the change*, not at release time.

06
Step 6: Audit for dead links and stale docs

CI job runs weekly: Check every internal link resolves Check every external link returns 2xx Flag any doc with last-updated > 180 days where the linked code has changed since Flag any TODO older than 90 days

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.