project-explanation

Project Explanation Skill

Generates engaging technical explanations of projects that preserve architectural wisdom and lessons learned.

What This Skill Does

Provides patterns, templates, and best practices for creating comprehensive technical documentation that:

• Explains complex systems clearly with analogies
• Justifies technology decisions
• Captures lessons learned and pitfalls
• Reads like an engaging essay, not boring documentation
• Preserves architectural knowledge for future engineers

When to Use

• Creating technical documentation for team onboarding
• Explaining project architecture to stakeholders
• Documenting technology decisions and trade-offs
• Preserving lessons learned from building a system
• Analyzing unfamiliar codebases

Core Principles

1. Clarity Through Analogy

Complex systems become understandable through comparison to familiar concepts.

Pattern:

"Think of [system] like [familiar thing]. [Familiar thing] does X, Y, Z.
Similarly, [system] does A, B, C to solve [problem]."

Examples:

• "Think of our cache like a store's back room. Items in the back room are grabbed quickly, but eventually expire and need restocking."
• "Our rate limiter is like a traffic light. It lets requests through quickly most of the time, but when traffic gets heavy, it queues them up."
• "Message queues are like mailboxes. You drop a letter in, the mailman delivers it eventually. You don't wait around for the delivery."

2. Lessons Through Anecdotes

People remember stories better than facts. Share how lessons were learned.

Pattern:

Lesson: [What was learned]
Story: "We discovered this when [situation]. [What happened].
        [How we fixed it]."
Takeaway: [How to apply in future]

Example:

Lesson: Database Migrations Need Careful Planning

Story: "We had a production database with 10 million user records. We wanted
to add a new column with a NOT NULL constraint. We didn't think to make it
nullable first, then backfill. We locked the entire table for 2 hours.
Customers couldn't log in. 😱"

Takeaway: For large tables, always backfill with nullable columns first,
then add constraints. Test on production volume in staging first.