Documentation Structure Patterns

Guidelines for organizing technical documentation based on codebase characteristics and team structure.

Pattern Selection Overview

Pattern A: Horizontal (Concern-Based)

Use when:

• Single codebase with clear separation of concerns
• Team of 5-15 people
• Traditional MVC or layered architecture
• Monolithic application or simple fullstack

Characteristics:

• Organized by technical concern (architecture, API, database, etc.)
• Easier for developers to find cross-cutting topics
• Works well when team members work across the stack

Structure Template

wiki/
├── README.md                    # Project overview and quick links
├── overview/
│   ├── system-overview.md       # What the system does
│   ├── technology-stack.md      # Languages, frameworks, tools
│   └── glossary.md              # Domain terminology
├── architecture/
│   ├── system-architecture.md   # High-level design
│   ├── data-model.md            # Database schema
│   └── api-design.md            # API patterns and conventions
├── development/
│   ├── getting-started.md       # Local setup guide
│   ├── coding-standards.md      # Style guide
│   └── testing.md               # Test strategy
├── deployment/
│   ├── infrastructure.md        # Cloud resources
│   ├── ci-cd.md                 # Pipeline documentation
│   └── environments.md          # Dev/staging/prod details
└── operations/
    ├── monitoring.md            # Observability setup
    ├── runbooks.md              # Incident procedures
    └── security.md              # Security practices

Navigation Pattern

# Project Wiki

## Quick Links
- [Getting Started](development/getting-started.md)
- [Architecture Overview](architecture/system-architecture.md)
- [API Reference](architecture/api-design.md)

## Sections
| Section | Description |
|---------|-------------|
| [Overview](overview/) | System purpose and technology |
| [Architecture](architecture/) | Design and technical decisions |
| [Development](development/) | Setup and coding practices |
| [Deployment](deployment/) | Infrastructure and CI/CD |
| [Operations](operations/) | Monitoring and security |

Pattern B: Vertical (Domain-Based)

Use when:

• Clear frontend/backend/integration separation
• 3+ external integrations
• Team of 10-30 people
• Multiple product domains or features

Characteristics:

• Organized by business domain or feature
• Easier for product teams to find relevant docs
• Works well when teams own specific domains

Structure Template

wiki/
├── README.md                    # Project overview
├── overview/
│   ├── system-overview.md
│   └── technology-stack.md
├── domains/
│   ├── user-management/
│   │   ├── README.md            # Domain overview
│   │   ├── authentication.md
│   │   ├── authorization.md
│   │   └── user-profiles.md
│   ├── billing/
│   │   ├── README.md
│   │   ├── subscriptions.md
│   │   ├── payments.md
│   │   └── invoicing.md
│   └── notifications/
│       ├── README.md
│       ├── email.md
│       ├── push.md
│       └── in-app.md
├── integrations/
│   ├── stripe.md
│   ├── sendgrid.md
│   └── twilio.md
├── platform/
│   ├── architecture.md
│   ├── infrastructure.md
│   └── security.md
└── development/
    ├── getting-started.md
    └── contributing.md

Navigation Pattern

# Project Wiki

## Domains
Each domain has its own documentation section:

| Domain | Owner | Description |
|--------|-------|-------------|
| [User Management](domains/user-management/) | Auth Team | Authentication, profiles |
| [Billing](domains/billing/) | Payments Team | Subscriptions, payments |
| [Notifications](domains/notifications/) | Platform Team | Email, push, in-app |

## Cross-Cutting
- [Integrations](integrations/) — Third-party services
- [Platform](platform/) — Shared infrastructure
- [Development](development/) — Setup and standards

Pattern C: Hybrid (Monorepo/Microservices)

Use when:

• Monorepo with multiple modules/services
• Microservices architecture
• Team of 20+ people with sub-teams
• Shared infrastructure with independent services

Characteristics:

• Combines concern-based and domain-based organization
• Each service/package has its own documentation
• Shared documentation for cross-cutting concerns

Structure Template

wiki/
├── README.md                    # Monorepo overview
├── overview/
│   ├── system-overview.md
│   ├── architecture.md          # System-wide architecture
│   └── technology-stack.md
├── services/
│   ├── api-gateway/
│   │   ├── README.md
│   │   ├── routing.md
│   │   └── authentication.md
│   ├── user-service/
│   │   ├── README.md
│   │   ├── api.md
│   │   └── data-model.md
│   ├── order-service/
│   │   ├── README.md
│   │   ├── api.md
│   │   └── workflows.md
│   └── notification-service/
│       ├── README.md
│       └── channels.md
├── packages/
│   ├── shared-ui/
│   │   └── README.md
│   ├── common-utils/
│   │   └── README.md
│   └── api-client/
│       └── README.md
├── infrastructure/
│   ├── kubernetes.md
│   ├── terraform.md
│   └── ci-cd.md
└── development/
    ├── getting-started.md
    ├── local-development.md
    └── service-template.md

Navigation Pattern

# Monorepo Wiki

## Services
| Service | Team | Port | Description |
|---------|------|------|-------------|
| [API Gateway](services/api-gateway/) | Platform | 3000 | Routing, auth |
| [User Service](services/user-service/) | Identity | 3001 | User management |
| [Order Service](services/order-service/) | Commerce | 3002 | Order processing |
| [Notification Service](services/notification-service/) | Platform | 3003 | Messaging |

## Shared Packages
| Package | Description |
|---------|-------------|
| [shared-ui](packages/shared-ui/) | React components |
| [common-utils](packages/common-utils/) | Utility functions |
| [api-client](packages/api-client/) | Generated API client |

## Platform
- [Infrastructure](infrastructure/) — Kubernetes, Terraform
- [Development](development/) — Setup, contributing

Pattern Selection Heuristics

Decision Tree

START
  │
  ├─ Is it a monorepo with multiple services/packages?
  │   ├─ YES → Pattern C (Hybrid)
  │   └─ NO ↓
  │
  ├─ Are there 3+ distinct business domains?
  │   ├─ YES → Pattern B (Vertical)
  │   └─ NO ↓
  │
  └─ Default → Pattern A (Horizontal)

Signals for Each Pattern

Pattern A signals:

• Single package.json or requirements.txt
• /src with /components, /services, /models structure
• One deployment unit
• Small team (< 15 people)

Pattern B signals:

• Multiple feature directories (/features/ or /domains/)
• Different teams own different areas
• Clear bounded contexts
• Multiple integration points

Pattern C signals:

• Multiple package.json files (monorepo)
• /services/ or /packages/ structure
• Docker Compose with multiple services
• Kubernetes deployments for multiple apps
• Shared libraries/packages

Naming Conventions

Folder Names

• Use kebab-case: user-management, api-gateway
• Match codebase naming where possible
• Be descriptive but concise

File Names

• Use kebab-case.md: system-architecture.md
• Pattern: <area>-<topic>.md or <domain>-<feature>.md
• Keep under 30 characters when possible

Section Organization

Each folder should have:

• README.md — Overview and navigation
• Topic files — Specific documentation
• No more than 7-10 files per folder (split if larger)

Page Planning Guidelines

For each page in your sitemap, define:

#### Page: `path/to/page.md`

**Purpose:** [1-2 sentences: what this page covers and why it matters]

**Required sections:**
- Section 1: [Description]
- Section 2: [Description]
- Code examples: Yes/No
- Tables: Yes/No

**Required diagrams:**
- [c4-context | c4-container | sequence | deployment | class | integration]

**Relevant source files:**
- `src/path/to/file.ts` — [Why relevant]
- `src/path/**/*.ts` — [Pattern/folder relevance]

**Cross-references:**
- Links to: [related pages]
- Linked from: [pages that reference this]

Navigation Rules

Index/Hub Pages

Every folder needs a README.md that:

1. Explains what the section covers
2. Lists all pages with brief descriptions
3. Provides quick links to common tasks

Breadcrumb Navigation

All pages should include: Home > [Section] > [Page]

*[Home](../README.md) > [Architecture](./README.md) > System Architecture*

# System Architecture
...

Cross-References

• Always use relative paths: [text](../path/to/page.md)
• Verify links exist in sitemap
• Make references bidirectional where appropriate

Versioning

Include in front matter:

---
title: Page Title
generated_at: 2026-01-22T10:00:00Z
commit: abc123 (if available)
last_updated: 2026-01-22T10:00:00Z
---

Scope Guidelines

Warning signs of over-documentation:

• More than 50 pages
• Pages with < 200 words
• Duplicate content across pages
• Pages that haven't been updated in 6+ months

Version: 1.0 Last Updated: 2026-01-22