Documentation Types
When to use each type of documentation - ADRs, Agreements, Processes, Guidelines, Solution Designs, and more
This guide explains the different types of documentation we maintain and when to use each one.
Documentation Types Overview
| Type | What | When to Create | Location | Example |
|---|---|---|---|---|
| ADR | High-level architectural decisions + WHY | When choosing architecture approach | /docs/architecture/{adr}/ | "Trunk-based development", "Microservices architecture" |
| Agreement | Technical standards and conventions | When selecting specific tools/practices | /docs/agreement/ | "PHPStan level 8 for PHP", "ESLint rules for TypeScript" |
| Process | Workflow - WHO, WHEN, WHAT sequence | When establishing new team process | /docs/process/ | "Duty Process", "Branch Strategy" |
| Solution Design | Feature/project design document | Before implementing major features | /docs/architecture/solution-designs/{number}/ | Feature design, System design |
| Test Design | Testing strategy for feature | Together with Solution Design | /docs/architecture/solution-designs/{number}/ | Feature test plan, QA strategy |
| C4 Diagram | Architecture visualization (4 levels) | When architecture changes | /docs/architecture/c4/ | System Context, Container diagram |
| Sequence Diagram | Step-by-step component interactions | When showing flow between services | /docs/architecture/sequence/ | Payment flow, Auth flow |
| ERD | Data structure and relationships | When designing/changing database | /docs/architecture/erd/ | Database schema |
| OpenAPI | REST API specification | When creating/modifying API | /openapi/ | API endpoints, schemas |
| Strategy | Architectural strategy documents | For long-term direction | /docs/architecture/strategy/ | Modernization approach |
When to Use Each Type
ADR (Architecture Decision Record)
Use when: You need to document a significant architectural decision that will impact the system long-term.
Examples:
- Choosing microservices vs monolith
- Selecting a database technology
- Deciding on authentication approach
- Trunk-based development vs GitFlow
Template: ADR Template
Agreement
Use when: Teams need to agree on technical standards, conventions, or tool configurations.
Examples:
- Code style rules (ESLint, Prettier configs)
- Linter levels (PHPStan level 8)
- Testing requirements
- Code review standards
Template: Agreement Template
Process
Use when: You need to document a workflow that involves multiple people and steps.
Examples:
- Duty support rotation process
- Branch strategy and PR workflow
- Release process
- Incident response procedure
Template: Process Template
Solution Design
Use when: Planning a significant feature or system component before implementation.
Examples:
- New payment processing feature
- Email notification system
- API versioning approach
- Data migration plan
Template: Solution Design Template
Test Design
Use when: Creating solution design - always pair these together.
Examples:
- Test strategy for new feature
- QA checklist
- Performance testing approach
- Integration test plan
Template: Test Design Template
C4 Diagram
Use when: Documenting system architecture at different abstraction levels.
The 4 Levels:
- System Context: High-level view showing users and external systems
- Container: Major building blocks (apps, databases, services)
- Component: Internal structure of containers
- Code: Class-level details (optional)
See: Diagram Guide
Sequence Diagram
Use when: Showing interactions between components over time.
Examples:
- API request flow
- Authentication process
- Payment transaction
- Data synchronization
Template: Sequence Diagram Template
ERD (Entity Relationship Diagram)
Use when: Designing or documenting database schema.
Examples:
- Database schema design
- Data model documentation
- Schema migration planning
Template: ERD Template
OpenAPI
Use when: Defining or documenting REST APIs.
Examples:
- API specification
- API contract definition
- API documentation
Process: Create YAML spec → Run pnpm build:openapi → Generated docs appear
Strategy
Use when: Documenting long-term architectural direction or approach.
Examples:
- Migration from monolith to microservices
- Technology modernization plan
- Platform evolution roadmap
Best Practices
Choose the Right Type
- ADR for decisions: Document WHY you chose something, not just WHAT
- Agreement for standards: Document what teams agreed to follow
- Process for workflows: Document WHO, WHEN, WHAT
- Solution Design before code: Always design before implementing features
Pair Related Documents
- Solution Design + Test Design: Always create together
- ADR + Agreement: Decisions often lead to standards
- Process + Guideline: Workflows often need implementation guides
Keep Documents Focused
- One document = one purpose
- Link between related documents
- Avoid duplicating information
Update Regularly
- Mark ADRs as Deprecated/Superseded when no longer valid
- Review Agreements periodically
- Keep Solution Designs as historical record (don't delete)
Examples
Real-World Examples
- ERD Validation: Example on GitHub
- Complete Solution Design: Example on GitHub