name	project-documentation-system
description	Create comprehensive project documentation including READMEs, contributing guides, ADRs, and architecture documentation

Project Documentation System

A comprehensive skill for creating, maintaining, and validating project documentation following industry best practices.

What This Skill Provides

Core Tools

Doc Generator - Create standard documentation from templates
ADR Creator - Document architecture decisions

Templates

README.md - Project overview and quick start
CONTRIBUTING.md - Contribution guidelines
ADR (Architecture Decision Records) - Document key decisions

Reference Documentation

Documentation Standards - Best practices and patterns
Template Guide - When and how to use each template

When to Use This Skill

Perfect For:

Starting new projects with proper documentation
Standardizing documentation across multiple projects
Creating Architecture Decision Records (ADRs)
Writing clear README files

Not For:

Code comments (that's inline documentation)
API documentation generation from code (use tools like Swagger/JSDoc)

Quick Start Workflows

Workflow 1: Bootstrap New Project Documentation

# Generate complete project documentation
python ~/my-skills/project-documentation-system/scripts/generate_docs.py \
  --project my-awesome-app \
  --type web-app \
  --tech "React, Node.js, PostgreSQL" \
  --all

# This creates:
# - README.md (with proper sections)
# - CONTRIBUTING.md (contribution guidelines)
# - LICENSE (MIT by default)
# - CHANGELOG.md
# - docs/ directory with architecture docs

Workflow 2: Create an Architecture Decision Record

# Document an important architectural decision
python ~/my-skills/project-documentation-system/scripts/create_adr.py \
  --title "Use PostgreSQL for primary database" \
  --status accepted

# Creates: docs/architecture/decisions/0001-use-postgresql.md

📖 Documentation Templates

README Template Structure

Every good README should have:

# Project Name

Brief description (1-2 sentences)

## Features
- Key feature 1
- Key feature 2

## Quick Start
```bash
npm install
npm start

Documentation

Contributing

See CONTRIBUTING.md

License

MIT


### ADR (Architecture Decision Record) Template

```markdown
# ADR-000X: [Title]

**Status:** [Proposed | Accepted | Deprecated]
**Date:** YYYY-MM-DD

## Context
What is the issue we're trying to solve?

## Decision
What did we decide to do?

## Consequences
What are the positive and negative consequences?

Documentation Types Reference

1. README.md

Purpose: Project overview and quick start Must include:

Project description
Installation instructions
Quick start guide
Link to detailed docs

2. CONTRIBUTING.md

Purpose: Guide for contributors Must include:

Development setup
Pull request process
Coding standards

3. Architecture Decision Records (ADRs)

Purpose: Document important technical decisions When to create:

Choosing technologies (database, framework)
Major architectural patterns
Security decisions

Documentation Quality Checklist

Essentials (Required)

README.md exists and is complete
Installation instructions are clear
All code examples work
Links are valid
License is specified

Best Practices (Recommended)

CONTRIBUTING.md exists
Architecture is documented (ADRs)
Changelog is maintained
Examples cover common use cases

Real-World Examples

Example 1: Quick Project Setup

cd my-new-project

# Bootstrap all documentation
python ~/my-skills/project-documentation-system/scripts/generate_docs.py \
  --project my-new-project \
  --type library \
  --tech "Python, FastAPI" \
  --all

# Result:
# ├── README.md
# ├── CONTRIBUTING.md
# ├── LICENSE
# ├── CHANGELOG.md
# └── docs/
#     └── architecture/
#         └── decisions/

Example 2: Document a Technical Decision

# Should we use Redis or Memcached?
python create_adr.py \
  --title "Use Redis for caching" \
  --status proposed

Common Documentation Problems & Solutions

Problem 1: Outdated Documentation

Symptom: Documentation doesn't match current code

Solutions:

Add doc validation to CI/CD
Review docs with every PR
Use automated tools to detect drift

Problem 2: Missing Context

Symptom: Readers don't understand why things are the way they are