Skip to content

Commit 211143e

Browse files
danielnaabdanielnaab
authored
Add documentation strategy and fill out documentation with more project context (#11)
1 parent 9ee5bd1 commit 211143e

5 files changed

Lines changed: 939 additions & 1 deletion

File tree

‎AGENTS.md‎

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,17 @@
11
# Repository Guidelines
22

3-
This guide helps contributors work effectively in the 10x Forms Platform monorepo.
3+
This guide helps AI agents and contributors work effectively in the Forms Platform monorepo.
4+
5+
## Documentation Index
6+
7+
For comprehensive documentation, see [DOCS.md](./DOCS.md).
8+
9+
**Quick links:**
10+
- [Quick Reference](./documents/quick-reference.md) - Common commands and workflows
11+
- [Patterns and Conventions](./documents/patterns-and-conventions.md) - Coding standards
12+
- [Architecture Overview](./documents/architecture.md) - System design
13+
- [Terminology](./documents/terminology.md) - Domain language
14+
- [ADRs](./documents/adr/) - Architectural decisions
415

516
## Project Structure & Module Organization
617

@@ -42,6 +53,17 @@ Tip: Tests that hit the database require Docker or Podman. Install Playwright br
4253
- Commits: follow Conventional Commits (e.g., `feat:`, `fix:`, `refactor:`). Include scope and ticket/issue (`TCKT-123`, `#123`) when relevant.
4354
- PRs: clear description, linked issues, screenshots for UI, tests updated, docs updated, and passing CI. One logical change per PR.
4455

56+
## Documentation Maintenance
57+
58+
When making code changes, update relevant documentation in the same PR:
59+
- Update package READMEs when public APIs change
60+
- Create ADR for significant architectural decisions (use next number in sequence)
61+
- Update [DOCS.md](./DOCS.md) when adding new documentation files
62+
- Keep [Quick Reference](./documents/quick-reference.md) current with command changes
63+
- Update [Patterns and Conventions](./documents/patterns-and-conventions.md) for new patterns
64+
65+
See [ADR 0018: Documentation Strategy](./documents/adr/0018-documentation-strategy.md) for complete guidelines.
66+
4567
## Security & Configuration Tips
4668

4769
- Never commit secrets. Use `.env` files (see examples like `e2e/.env.sample`).

‎DOCS.md‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
# Documentation Index
2+
3+
This index helps you navigate all Forms Platform documentation.
4+
5+
## Quick Start
6+
7+
**New to the project?** Start here:
8+
1. [README.md](./README.md) - Project overview and setup
9+
2. [AGENTS.md](./AGENTS.md) - AI agent guidelines and repository structure
10+
3. [Quick Reference](./documents/quick-reference.md) - Common commands and workflows
11+
4. [Architecture Overview](./documents/architecture.md) - System design and component relationships
12+
13+
**Using Claude Code?** See [CLAUDE.md](./CLAUDE.md) for Claude-specific guidance.
14+
15+
## Documentation by Purpose
16+
17+
### Understanding the System
18+
19+
**Core Concepts**
20+
- [Architecture Overview](./documents/architecture.md) - System design, packages, data flows
21+
- [Terminology](./documents/terminology.md) - Domain language (blueprints, patterns, prompts, components)
22+
- [DOJ Deployment Diagram](./documents/doj-diagram.md) - Department of Justice specific architecture
23+
24+
**Patterns & Conventions**
25+
- [Patterns and Conventions](./documents/patterns-and-conventions.md) - Coding standards, naming, architecture patterns
26+
- [Pattern System](./packages/forms/src/patterns/README.md) - Form building blocks and pattern usage
27+
28+
### Building and Developing
29+
30+
**Getting Started**
31+
- [Quick Reference](./documents/quick-reference.md) - Common commands, workflows, troubleshooting
32+
- [Podman Integration](./documents/podman-integration.md) - Development environment setup with Podman/Docker
33+
34+
**Package Documentation**
35+
- [Forms Package](./packages/forms/README.md) - Core business logic, services, patterns
36+
- [Design Package](./packages/design/README.md) - UI components and Storybook
37+
- [Server Package](./packages/server/README.md) - Node.js web server (Astro + Express)
38+
- [Auth Package](./packages/auth/README.md) - Authentication and authorization
39+
- [Database Package](./packages/database/README.md) - PostgreSQL/SQLite with Kysely and Knex
40+
- [Common Package](./packages/common/README.md) - Shared utilities
41+
42+
**Application Documentation**
43+
- [Spotlight App](./apps/spotlight/README.md) - Main Astro website
44+
- [CLI App](./apps/cli/README.md) - Command-line interface
45+
- [Sandbox App](./apps/sandbox/README.md) - Testing and demo application
46+
- [Server DOJ App](./apps/server-doj/README.md) - Department of Justice server instance
47+
48+
**Testing**
49+
- [E2E Testing](./e2e/README.md) - Playwright end-to-end tests
50+
- [ADR 0010: End-to-End Testing](./documents/adr/0010-end-to-end-testing.md) - E2E testing strategy
51+
52+
### Operations and Deployment
53+
54+
**Release and Deployment**
55+
- [Release Process](./documents/release-process.md) - How to release new versions
56+
- [ADR 0003: Initial Deployment Choices](./documents/adr/0003-initial-deployment-choices.md)
57+
- [ADR 0004: Infrastructure as Code](./documents/adr/0004-infrastructure-as-code.md)
58+
59+
**Infrastructure**
60+
- [AWS CDK Infrastructure](./infra/aws-cdk/README.md) - AWS deployment
61+
- [Terraform CDK Infrastructure](./infra/cdktf/README.md) - Terraform deployment
62+
- [Core Infrastructure](./infra/core/README.md) - Shared infrastructure utilities
63+
64+
**Security**
65+
- [ADR 0011: Secrets Management](./documents/adr/0011-secrets-management.md)
66+
- [ADR 0014: Authentication](./documents/adr/0014-authentication.md)
67+
68+
### Architectural Decisions
69+
70+
All architectural decisions are documented as ADRs in [documents/adr/](./documents/adr/). Key decisions:
71+
72+
**System Architecture**
73+
- [ADR 0001: Record Architecture Decisions](./documents/adr/0001-record-architecture-decisions.md)
74+
- [ADR 0005: Build System](./documents/adr/0005-build-system.md) - Turborepo + pnpm workspaces
75+
- [ADR 0013: Database Strategy](./documents/adr/0013-database-strategy.md) - PostgreSQL, SQLite, Kysely, Knex
76+
- [ADR 0015: REST API](./documents/adr/0015-rest-api.md)
77+
- [ADR 0018: Documentation Strategy](./documents/adr/0018-documentation-strategy.md)
78+
79+
**Frontend & Design**
80+
- [ADR 0006: Spotlight Frontend](./documents/adr/0006-spotlight-frontend.md) - Astro framework
81+
- [ADR 0007: Initial CSS Strategy](./documents/adr/0007-initial-css-strategy.md)
82+
- [ADR 0009: Design Assets Workflow](./documents/adr/0009-design-assets-workflow.md)
83+
- [ADR 0012: Rich Text Editor](./documents/adr/0012-rich-text-editor.md)
84+
- [ADR 0016: Unused CSS](./documents/adr/0016-unused-css.md)
85+
86+
**Code Quality**
87+
- [ADR 0017: Use Named Exports](./documents/adr/0017-use-named-exports.md)
88+
- [ADR 0002: Generate Dependency Diagram](./documents/adr/0002-generate-dependency-diagram.md)
89+
90+
**Domain Logic**
91+
- [ADR 0008: Initial Form Handling Strategy](./documents/adr/0008-initial-form-handling-strategy.md)
92+
93+
### Reference
94+
95+
**Sample Documents**
96+
- [California Unlawful Detainer](./packages/forms/sample-documents/ca-unlawful-detainer/README.md)
97+
- [DOJ Pardon Marijuana](./packages/forms/sample-documents/doj-pardon-marijuana/README.md)
98+
99+
**Work in Progress**
100+
- [Pending Loose Ends](./documents/pending-loose-ends.md) - Known gaps and future work
101+
102+
## Documentation Maintenance
103+
104+
When making code changes:
105+
1. Update relevant documentation in the same PR
106+
2. Create ADR for significant architectural decisions
107+
3. Update package READMEs when public APIs change
108+
4. Keep this index current when adding new documentation
109+
110+
See [ADR 0018: Documentation Strategy](./documents/adr/0018-documentation-strategy.md) for complete guidelines.

‎documents/adr/0018-documentation-strategy.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# 18. Documentation Strategy for AI Agents and Developers
2+
3+
Date: 2025-10-05
4+
5+
## Status
6+
7+
Accepted
8+
9+
## Context
10+
11+
Forms Platform requires documentation that serves two audiences: human developers and AI coding agents. Existing documentation includes READMEs, ADRs, AGENTS.md, CLAUDE.md, and various technical guides. However, the documentation lacks:
12+
13+
1. A clear navigation structure for discovery
14+
2. Consistent organization across documents
15+
3. Optimization for AI agent context windows
16+
4. Clear maintenance guidelines
17+
18+
Research shows AI agents work best with:
19+
- Progressive disclosure (index → summary → details)
20+
- Context-efficient, modular documentation
21+
- Specific, descriptive titles (not generic "Overview")
22+
- Plain language with direct, unambiguous phrasing
23+
- Clear cross-references between related concepts
24+
25+
The AGENTS.md standard has emerged as best practice for AI coding agents, adopted by 20,000+ repositories.
26+
27+
## Decision
28+
29+
We implement a six-layer documentation architecture:
30+
31+
### Layer 1: Navigation (Discovery)
32+
- `DOCS.md` - Master documentation index with categorized links
33+
- `AGENTS.md` - AI agent quick start and repository guidelines
34+
- `CLAUDE.md` - Claude Code-specific configuration and patterns
35+
- `README.md` - Project overview and getting started
36+
37+
### Layer 2: Quick Reference (Common Tasks)
38+
- `documents/quick-reference.md` - Commands, workflows, troubleshooting
39+
- Organized by: Setup, Development, Testing, Deployment, Common Issues
40+
41+
### Layer 3: Concepts & Patterns (How We Build)
42+
- `documents/patterns-and-conventions.md` - Coding standards, architecture patterns
43+
- `documents/terminology.md` - Domain language (ubiquitous language)
44+
- `documents/architecture.md` - System architecture and component relationships
45+
46+
### Layer 4: Decisions & History (Why We Build This Way)
47+
- `documents/adr/` - Architecture Decision Records (numbered NNNN-title.md)
48+
- Standard format: Status, Context, Decision, Consequences
49+
50+
### Layer 5: Operations (Running the System)
51+
- `documents/release-process.md` - Release workflow
52+
- `documents/podman-integration.md` - Development environment setup
53+
- Other operational guides as needed
54+
55+
### Layer 6: Package-Specific (Deep Dives)
56+
- Package-level READMEs in each workspace package
57+
- Detailed API documentation and implementation notes
58+
59+
### Documentation Standards
60+
61+
**File Naming**
62+
- Use descriptive, specific names: `authentication-flow.md` not `overview.md`
63+
- Use kebab-case for filenames
64+
- ADRs follow pattern: `NNNN-descriptive-title.md`
65+
66+
**Content Structure**
67+
- Start each document with one-sentence purpose statement
68+
- Use consistent heading hierarchy (##, ###)
69+
- Include "See also" sections for related documents
70+
- Keep sentences short and direct
71+
- Use bullet lists for scannability
72+
- Provide code examples where helpful
73+
- Avoid duplication - link to authoritative source
74+
75+
**Maintenance Process**
76+
- Documentation changes in same PR as related code changes
77+
- AI agents must update relevant docs when implementing features
78+
- Create new ADR for any significant architectural decision
79+
- Regular documentation review to identify gaps and outdated content
80+
81+
**AI Agent Optimization**
82+
- Keep documents focused and modular (< 500 lines preferred)
83+
- Use specific, searchable titles
84+
- Include clear summary at document start
85+
- Cross-reference related documents
86+
- Avoid verbose explanations - prefer direct statements
87+
88+
## Consequences
89+
90+
### Positive
91+
- AI agents can quickly discover relevant documentation via DOCS.md index
92+
- Modular structure reduces context window usage
93+
- Clear maintenance guidelines ensure documentation stays current
94+
- Progressive disclosure serves both quick lookups and deep research
95+
- Consistent structure reduces cognitive load
96+
- Single source of truth reduces contradictions
97+
98+
### Negative
99+
- Requires initial effort to create new documentation
100+
- Developers must maintain documentation alongside code
101+
- Additional files to track in version control
102+
103+
### Mitigation
104+
- AI agents can generate initial documentation from existing code
105+
- Documentation updates are mandatory part of code review
106+
- Clear templates reduce friction for creating new docs
107+
- Index structure makes it easy to find and update docs

0 commit comments

Comments
 (0)