project-documentation

name

project-documentation

description

Comprehensive codebase documentation generator following a layered methodology. This skill should be used when scanning and documenting a codebase for the first time, when creating onboarding documentation for new developers, when generating architecture overviews, walkthroughs, and API references. Supports README generation, architecture diagrams, entry point documentation, pattern guides, and edge case documentation.

Project Documentation

Comprehensive skill for scanning codebases and generating layered documentation to help developers get familiar quickly.

Overview

This skill implements a 6-phase documentation methodology:

1. Understand - Explore codebase before documenting
2. Structure - Create layered documentation (high/mid/low level)
3. Essential Docs - Generate core documents
4. Functions - Document code with intent
5. Onboarding - Create self-paced learning materials
6. Maintain - Keep documentation versioned and searchable

Documentation Workflow

Phase 1: Understand Before Documenting

Before writing documentation, thoroughly explore the codebase:

1. Explore Version Control History

   git log --oneline -50           # Recent changes
   git log --all --oneline --graph # Visual branch history
   git shortlog -sn                # Top contributors
   

2. Analyze Code Structure

   • Run tree -L 3 -I node_modules for structure
   • Identify entry points (main., index., app.*)
   • Detect framework patterns (React, Express, FastAPI, etc.)

3. Read Development Tests

   • Tests reveal how code is intended to work
   • Failed test history shows fixed issues
   • Test structure mirrors code architecture

4. Trace Execution Flows

   • Follow imports from entry points
   • Map API routes to handlers
   • Document data flow patterns

Phase 2: Create Layered Documentation

Generate three documentation layers:

Layer	Purpose	Audience	Location
High-Level	Architecture, design principles	New devs, stakeholders	docs/architecture/
Walkthrough	Flows, patterns, interactions	Contributing devs	docs/walkthroughs/
Low-Level	Functions, parameters, returns	Active maintainers	Inline + docs/api/

Phase 3: Essential Documents

Generate using templates in templates/:

1. README.md - See templates/readme-template.md
2. Architecture Overview - See templates/architecture-template.md
3. Walkthrough Guide - See templates/walkthrough-template.md
4. API/Function Reference - See templates/api-reference-template.md
5. Setup Guide - See templates/setup-guide-template.md

Phase 4: Document Functions Effectively

When documenting individual functions:

• Describe WHY, not just WHAT - Business assumptions, algorithm steps
• Use meaningful names - Self-documenting code
• Document intent - Design choices, trade-offs
• Include examples - Expected usage patterns

Reference: references/function-documentation.md

Phase 5: Onboarding-Focused Documentation

Create self-paced onboarding materials:

• Clear language - Avoid jargon without explanation
• Code snippets - Illustrate concepts with examples
• Consistent naming - Classes, functions, variables, files
• Decision rationale - Explain coding decisions

Phase 6: Maintainability

• Version documentation with source code
• Make documentation searchable
• Link from team communication channels
• Incrementally improve as codebase evolves

Documentation Priority Order

Generate documentation in this order:

1. README with setup instructions (get developers running)
2. Architecture diagram showing major components
3. Entry points documentation (where code starts)
4. Core patterns used throughout codebase
5. Key functions/modules with purpose and examples
6. Edge cases and gotchas that trip up newcomers

Output Structure

docs/
├── README.md                    # Project overview
├── architecture/
│   ├── overview.md              # System architecture
│   ├── components.md            # Component descriptions
│   └── diagrams/                # Architecture diagrams
├── walkthroughs/
│   ├── entry-points.md          # Where code starts
│   ├── data-flow.md             # How data moves
│   └── patterns.md              # Recurring patterns
├── api/
│   ├── endpoints.md             # API endpoints
│   └── functions.md             # Key functions
├── setup/
│   ├── installation.md          # Installation guide
│   ├── configuration.md         # Configuration options
│   └── troubleshooting.md       # Common issues
└── onboarding/
    ├── quickstart.md            # 5-minute start
    ├── tutorials/               # Hands-on tutorials
    └── gotchas.md               # Edge cases & tips

Scanning Checklist

• Version control history analyzed
• Project type and framework identified
• Entry points documented
• Directory structure mapped
• Dependencies catalogued
• Key patterns identified
• Configuration files documented
• README created/updated
• Architecture overview generated
• Walkthrough guides created
• API reference generated
• Setup guide complete
• Onboarding materials ready