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.
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
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.
user-invocable
false
Documentation Structure Patterns
Guidelines for organizing technical documentation based on codebase characteristics and team structure.
Pattern Selection Overview
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
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
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:
Explains what the section covers
Lists all pages with brief descriptions
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)
