Guide for documenting system concepts (factories, seeding, patterns, architecture decisions) with focus on human-readable explanations over code. Reference code files instead of embedding. Use when documenting backend systems, data models, architectural patterns, or any non-component technical concepts.
Create comprehensive documentation for system concepts like factories, seeding, architecture patterns, and technical decisions. The goal is exhaustive but sane documentation - complete coverage without unnecessary fragmentation.
This skill differs from component-documenter which focuses on UI component documentation with props, hooks, and visual rendering. Use this skill for backend systems, data flows, architectural decisions, and non-visual technical concepts.
When documenting a complex system, create a dedicated folder under docs/:
docs/
[topic]/
README.md # Index with overview and navigation
architecture.md # System design, key decisions
data-model.md # Schema, types, relationships
operations.md # Queries, workflows, configuration (consolidated)
[topic-specific].md # Domain-specific docs as needed
Consolidate into single files:
operations.md)Keep separate:
Do this:
The
UserFactorygenerates test users with randomized but realistic data. It uses Faker for name generation and creates associated profile records automatically.
Not this:
// 50 lines of factory code copied here
When referencing code, always generate clickable GitHub permalinks that point to the exact commit, so links remain stable over time.
Permalink format: