Plan: Comprehensive Documentation Overhaul

On this page

Status

Phase Description Status

0

Create canonical plan document, link in nav, create GitLab issue

Done (pre-ADR-030)

A

Nav restructure + plan archive + stub pages

Done (pre-ADR-030)

B+G

CLAUDE.md decomposition + governance conventions

Done (pre-ADR-030)

C

Plan template + retroactive standardization

Done (pre-ADR-030)

D

Configuration reference + troubleshooting pages

Done (pre-ADR-030)

E

Antora search enablement

Done (pre-ADR-030)

F

User guides (caseworker, supervisor, admin, public reporting)

Done (pre-ADR-030)

Branch: feature/documentation-overhaul

Context

CRAIG’s documentation has grown organically across 12 phases of development. While the content is largely accurate and comprehensive, the organization has not kept pace:

  1. nav.adoc lists 35 plans in a flat list (mixing complete, active, and deferred) — overwhelming and unscannable

  2. CLAUDE.md is a 187-line monolith covering 7 distinct concerns — delivery protocol, coding conventions, plans rules, testing, doc checklist, git workflow, and GitLab standards

  3. No plan template — quality ranges from excellent to stub

  4. No end-user documentation — caseworkers, supervisors, and admins have no workflow guides

  5. Missing developer reference pages — configuration reference, troubleshooting

  6. No search — Antora supports Lunr but it’s not configured

  7. No governance rules — nothing prevents docs from becoming disorganized again after this overhaul

Audience Map

Audience What they need Current state Gap

Agency decision-makers

Why CRAIG, federal compliance, cost

why-craig.adoc, federal-requirements.adoc

Adequate

Evaluators/testers

Setup, explore, test drive

user-testing-guide.adoc, mock screens

Adequate

Caseworkers

How to do intake, manage cases, placements

Design specs (what screens look like)

No procedural/workflow docs

Supervisors

Approval flows, dashboard, caseload oversight

Design specs

No role-specific guides

Administrators

System config, user management, rules, security

Deployment guide (infra only)

No admin operations guide

Developers

Architecture, API, contributing, devstack

Extensive

Needs reorganization

AI agents

Coding rules, delivery protocol, conventions

.claude/ docs

CLAUDE.md too monolithic

Scope

In scope:

  • Restructure Antora nav into 6-section hierarchy

  • Archive 21+ completed plans into a single index page

  • Decompose CLAUDE.md into focused single-concern files

  • Create plan template for future consistency

  • Add user guides for caseworkers, supervisors, admins, and public reporters

  • Add configuration reference and troubleshooting pages

  • Enable Antora Lunr search

  • Establish governance conventions to prevent future disorganization

Out of scope:

  • Content accuracy audits (already done in prior session)

  • In-app help text or tooltips

  • Video walkthroughs

  • Jurisdiction-specific procedure manuals

Design

This plan uses 7 phases (A through G, with G merged into B’s MR). Phases A, B, and E are independent and can proceed in parallel. Phases C, D, and F depend on Phase A.

The full implementation details — including exact file contents, derivation instructions, and source file references — are maintained in the working plan at .claude/plans/atomic-launching-tower.md.

Steps

Phase A: Nav Restructure + Plan Archive

Branch: feature/docs-nav-restructure
Files: nav.adoc, plans/archive.adoc, 6 stub pages in guide/ and developer guide

  1. Create plans/archive.adoc with completed plans grouped by category (Features, Infrastructure, Code Quality, Testing & Documentation) with xref links and MR numbers

  2. Rewrite nav.adoc with 6-section hierarchy: Getting Started, User Guide, Architecture & Design, Developer Guide, Operations, Plans (Active/Planned/Deferred/Archive)

  3. Create stub pages for future content: guide/caseworker.adoc, guide/supervisor.adoc, guide/admin.adoc, guide/public-reporting.adoc, configuration-reference.adoc, troubleshooting.adoc

  4. Verify: npx antora antora-playbook.yml — zero broken xref warnings

Phase B+G: CLAUDE.md Decomposition + Governance

Branch: feature/docs-claude-decomposition
Files: CLAUDE.md, 4 new files in .claude/docs/, update testing.md

  1. Create .claude/docs/delivery-protocol.md — delivery checklist, doc update checklist, plan completion audit (with governance additions: user guide checklist item, expanded audit)

  2. Create .claude/docs/coding-conventions.md — Rust/cargo, Docker, DB migrations, plan authoring, plan lifecycle rules, nav structure rules

  3. Create .claude/docs/git-workflow.md — branching, MRs, conflicts, work claiming

  4. Create .claude/docs/known-issues.md — known issues + lessons learned

  5. Prepend mandatory testing rules to existing .claude/docs/testing.md

  6. Rewrite .claude/CLAUDE.md as ~95-line orchestrator with Required Reading links

  7. Verify: no content lost (diff check), all links resolve, under 100 lines

Phase C: Plan Template + Standardization

Branch: feature/docs-plan-template (depends on Phase A)
Files: plans/_template.adoc, 3-4 plan files

  1. Create plans/_template.adoc with mandatory sections: Status, Context, Scope, Steps, Files Touched, Verification, Documentation Updates

  2. Add template reference to coding-conventions.md

  3. Retroactively add missing Status sections to plans that lack them

Phase D: New Developer Content Pages

Branch(es): feature/docs-config-reference, feature/docs-troubleshooting (depends on Phase A)
Files: configuration-reference.adoc, troubleshooting.adoc

  1. Replace config reference stub with full page: one table per service, all env vars from each service’s config.rs

  2. Replace troubleshooting stub with categorized guide: Docker/devstack, Testing, Development, CI

Phase E: Search Enablement

Branch: feature/docs-search
Files: antora-playbook.yml, .gitlab-ci.yml

  1. Add @antora/lunr-extension to playbook

  2. Update CI npm install commands in review and pages jobs

  3. Verify search box appears and returns results

Phase F: User Guides

Branch: feature/docs-user-guides (depends on Phase A)
Files: 4 guide pages, 4 design spec cross-links

  1. Replace caseworker guide stub: intake, case management, placement, data exchange, financial (view-only), common tasks quick reference

  2. Replace supervisor guide stub: dashboard supervisor view, caseload management, reports, security & audit

  3. Replace admin guide stub: user management, rules config, admin units, exchange partners, security, system health

  4. Replace public reporting guide stub: form walkthrough, after submitting, status checking, confidentiality, emergencies

  5. Add cross-link admonitions to design spec pages (intake, case-management, placement, reporting)

Verification

  1. npx antora antora-playbook.yml — zero warnings after each phase

  2. Every .adoc file under pages/plans/ reachable from nav or archive

  3. Fresh agent session can find delivery protocol, testing rules, and git workflow from CLAUDE.md links

  4. A developer navigates index → developer guide → devstack in 4 clicks

  5. A caseworker navigates index → user guide → caseworker guide and finds workflow instructions

  6. Every audience in the Audience Map has a clear entry point in the nav

Documentation Updates

  • CHANGELOG.adoc — entry under == Unreleased

  • .claude/CLAUDE.md — restructured as part of this plan

  • .claude/docs/ — new and updated files as part of this plan

Edit this page · latest