Help us improve
Share bugs, ideas, or general feedback.
From deepwiki
Documentation structure heuristics and sitemap patterns for different codebase types and team sizes. Covers horizontal (concern-based), vertical (domain-based), and hybrid patterns. Use when planning documentation organization.
npx claudepluginhub gravity9-tech/claude_code_marketplace_demo --plugin deepwikiHow this skill is triggered — by the user, by Claude, or both
Slash command
/deepwiki:documentation-structure-patternsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Guidelines for organizing technical documentation based on codebase characteristics and team structure.
Guides project documentation structure, file organization, content requirements by project phase, and best practices for README.md, ARCHITECTURE.md, API docs, and more.
Establish documentation standards that keep docs current, discoverable, and useful. Use when scaling team or improving knowledge retention.
Documentation levels and types (README, architecture, API, runbooks), keeping docs current and discoverable.
Share bugs, ideas, or general feedback.
Guidelines for organizing technical documentation based on codebase characteristics and team structure.
| Pattern | Best For | Team Size | Example Projects |
|---|---|---|---|
| Pattern A (Horizontal) | Single codebase, clear concerns | 5-15 people | Fullstack SPA, monolithic API |
| Pattern B (Vertical) | Multiple domains, clear boundaries | 10-30 people | Multi-product platform, B2B SaaS |
| Pattern C (Hybrid) | Monorepo, microservices | 20+ people | Enterprise platform, large open source |
Use when:
Characteristics:
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
# 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 |
Use when:
Characteristics:
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
# 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
Use when:
Characteristics:
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
# 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
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)
Pattern A signals:
package.json or requirements.txt/src with /components, /services, /models structurePattern B signals:
/features/* or /domains/*)Pattern C signals:
package.json files (monorepo)/services/* or /packages/* structurekebab-case: user-management, api-gatewaykebab-case.md: system-architecture.md<area>-<topic>.md or <domain>-<feature>.mdEach folder should have:
README.md — Overview and navigationFor 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]
Every folder needs a README.md that:
All pages should include: Home > [Section] > [Page]
*[Home](../README.md) > [Architecture](./README.md) > System Architecture*
# System Architecture
...
[text](../path/to/page.md)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
---
| Project Size | Recommended Pages | Pattern |
|---|---|---|
| Small (< 10k LOC) | 5-10 pages | Pattern A |
| Medium (10k-100k LOC) | 10-20 pages | Pattern A or B |
| Large (100k+ LOC) | 15-30 pages | Pattern B or C |
| Monorepo | 20-50 pages | Pattern C |
Warning signs of over-documentation:
Version: 1.0 Last Updated: 2026-01-22