project-documentation

Project Documentation

Create clear, complete, and user-friendly README and system documentation for software projects.

Core Capabilities

This skill helps you create high-quality project documentation with:

1. Mermaid Flowcharts - Visualize system operation principles
2. Step-by-Step Instructions - Detailed beginner-friendly guides
3. Configuration Documentation - Clear organization of environment variables and config files

Workflow

1. Understand the Project

Before writing documentation, gather essential information:

• Project's core features and purpose
• Tech stack (frontend, backend, database, external services)
• User workflows (startup process, core operations)
• External dependencies (API Keys, accounts, tools)
• Configuration items (required vs optional)

Information sources: README, package.json, .env.example, main code files (main.ts, app.ts, routes/)

2. Create Mermaid Flowcharts

Choose appropriate diagrams based on project needs:

• Core Flow Diagram (Required) - User operation flow from startup to task completion
• Data Flow Diagram (Recommended) - System component interactions and API calls
• Technical Architecture Diagram (Recommended) - Tech stack and layered structure

Complete templates and patterns: See references/mermaid-patterns.md

3. Write Step-by-Step Instructions

Organize usage steps in this sequence:

1. Prerequisites (software, accounts, tools)
2. Clone project and install dependencies
3. Obtain external service credentials (if needed)
4. Configure environment variables
5. Initialize system (if needed)
6. Start services
7. Use features
8. Verify system operation

Each step should include: Purpose, commands, expected output, tips, and warnings.

Complete writing guide: See references/step-by-step-guide.md

4. Organize Configuration Documentation

Structure .env.example with clear separators:

# ========================================
# Main Category Title
# ========================================
CONFIG_ITEM=example_value

# ----------------------------------------
# Subcategory Title
# ----------------------------------------
CONFIG_ITEM=example_value

Document each configuration item with:

• Required vs optional status
• Purpose and usage
• Acquisition method (for external services)
• Default values
• Complete examples

Complete organization guide: See references/config-organization.md

5. Recommended README Structure

# Project Name - Brief Description
## Features
## System Operation Principles (Mermaid diagrams)
## Quick Start (Step by Step)
## Common Commands
## API Examples
## Tech Stack
## Project Structure
## Documentation
## Important Notes
## License

Quality Checklist

Before finalizing documentation:

Flowcharts:

• Core flow shows user operations clearly
• Data flow reflects system interactions accurately
• Architecture diagram shows complete tech stack
• Appropriate colors and moderate complexity (<20 nodes)

Usage Steps:

• Complete prerequisites list
• Clear titles and purpose for each step
• Copy-paste ready commands
• Expected output explained
• Common problem tips included

Configuration:

• Required vs optional clearly marked
• Purpose explained for each item
• Acquisition methods provided
• Clear separators and grouping
• Multi-option comparisons (if applicable)

User-Friendliness:

• Clear icons used (✅ ⚠️ 💡)
• Multiple options provided (if applicable)
• Troubleshooting tips included
• Concise and clear language
• All links accessible

Reference Resources

• mermaid-patterns.md - Flowchart design patterns and templates
• step-by-step-guide.md - Step-by-step instruction writing guide
• config-organization.md - Configuration documentation organization guide
• complete-example.md - Complete documentation example with all three diagram types

Best Practices

1. User Perspective First - Assume zero background knowledge
2. Actionability - All commands should be copy-pasteable
3. Completeness - Include all necessary information
4. Clarity - Use diagrams, tables, code blocks
5. Verifiability - Provide verification steps

Common Scenarios

New Project: Understand structure → Create diagrams → Write steps → Organize config → Verify quality

Update Existing: Read current README → Identify gaps → Add/optimize content → Verify quality

Optimize Config: Group by function → Add separators → Mark required/optional → Link acquisition methods