| name | technical-writer |
| description | Write technical tutorials, blog posts, and educational content with pedagogical structure. Covers concept explanations, how-to guides, deep dives, and developer education. Triggers on tutorial, technical article, blog post, explain concept, teach, educational content, developer guide. |
Technical Writer
For README-specific patterns (hero, TL;DR, quick start), see readme-craft skill.
Content Types & Writing Guidelines
1. Concept Explanation
Build mental models for abstract ideas.
# [Concept Name]
## The Problem It Solves
[Concrete scenario where this matters - make the reader FEEL the pain]
## The Core Idea
[One paragraph, one analogy, zero jargon]
## How It Works
[Visual or step-by-step breakdown]
### Step 1: [First thing that happens]
### Step 2: [Next thing]
### Step 3: [Result]
## In Practice
[Code example with annotations]
## Common Misconceptions
- **Myth:** [What people wrongly believe]
- **Reality:** [What's actually true]
## When NOT to Use This
[Explicit boundaries - this builds trust]
Opening example:
Bad: "Dependency injection is a design pattern where..."
Good: "Your class needs a database connection. Do you create it inside the class, or pass it in from outside? This choice determines whether your code is testable or a nightmare."
Voice: "This works because..." not "As you can see...". "You might expect X, but actually Y" not "Obviously...". Never "simply" or "just" (these dismiss difficulty).
2. How-To Guide
Get the reader from A to B with minimum friction.
# How to [Accomplish Specific Goal]
**Time:** X minutes | **Difficulty:** Beginner/Intermediate/Advanced
## What You'll Build
[Screenshot or description of end result]
## Prerequisites
- [Specific tool/version]
- [Knowledge assumed]
## Steps
### 1. [Action verb] [Object]
[Why this step matters - one sentence]
```code
[Exact command or code]
Expected result: [What they should see]
2. [Next action]
[Continue pattern]
Verify It Works
[Test command or manual verification]
Troubleshooting
[Error message or symptom]
Cause: [Why this happens]
Fix: [Exact solution]
Next Steps
- [Related guide]
- [Advanced topic]
**Rules:** One action per step. Every step has expected output. Code is copy-paste ready.
### 3. Tutorial (Teaching Through Building)
Teach concepts by building something real.
```markdown
# Build [Something Concrete]
## What You'll Learn
By the end, you'll understand:
- [Concept 1]
- [Concept 2]
- [Concept 3]
## The Project
[Description of what we're building and why it's useful]
## Part 1: [Foundation]
### The Concept
[Brief explanation of the underlying idea]
### Implementing It
[Code with inline explanation]
### What Just Happened
[Reinforce the concept with what they just did]
## Part 2: [Build on Foundation]
[Repeat pattern, each part introducing one new concept]
## Recap
| Concept | Where We Used It |
|---------|------------------|
| [Concept 1] | Part 1 - [specific code] |
| [Concept 2] | Part 2 - [specific code] |
## Challenges
1. **[Easy extension]** - [Hint]
2. **[Medium extension]** - [Hint]
3. **[Hard extension]** - [Hint]
Rules: One concept per section. Build something that actually works. Show mistakes and corrections. Include checkpoints to verify progress.
4. Deep Dive / Technical Article
Comprehensive exploration for mastery-level readers.
# [Topic]: A Deep Dive
**Reading time:** X minutes | **Audience:** [Intermediate/Advanced] developers
## TL;DR
[3-5 bullet points covering the key insights]
## The Landscape
[Context: what exists, what problem space we're in]
## How [Thing] Actually Works
### Under the Hood
[Technical explanation with diagrams/code]
### The Tradeoffs
| Approach | Pros | Cons | Use When |
|----------|------|------|----------|
| A | | | |
| B | | | |
## Real-World Patterns
### Pattern 1: [Name]
[Code example from production-quality source]
## Common Pitfalls
### Pitfall 1: [Name]
**The mistake:**
```code
[Bad code]
The fix:
[Good code]
Why: [Explanation]
Further Reading
- [Resource 1] - [What it covers]
## Code Examples
**Every code block needs:**
1. Context (what file, what situation)
2. Working code (not pseudocode unless explicitly stated)
3. Key lines highlighted or annotated
```python
# user_service.py - handling authentication
def authenticate(self, credentials):
user = self.repository.find_by_email(credentials.email)
if not user:
return AuthResult.failure("User not found") # <- Early return pattern
if not user.verify_password(credentials.password):
return AuthResult.failure("Invalid password")
return AuthResult.success(user) # <- Only success path reaches here
Explaining code:
Bad: "This code authenticates the user."
Good: "We check for failure conditions first (lines 4-8), returning early. Only valid credentials reach the success path on line 10. This 'guard clause' pattern keeps the happy path unindented."
Analogies
Bridge unfamiliar concepts to familiar ones:
| Concept | Analogy |
|---|
| API rate limiting | Bouncer at a club only letting in X people per hour |
| Database indexing | Index in a textbook vs. reading every page |
| Caching | Keeping frequently-used items on your desk vs. filing cabinet |
| Load balancing | Multiple checkout lanes at a grocery store |
Rules: Map key properties (not just surface similarity). Acknowledge where the analogy breaks down. Use familiar domains (not other technical concepts).
Handling Complexity
- Start with the simple case - "In the basic scenario, X happens"
- Add one complication - "But what if Y?" Show how the solution adapts
- Show the full picture - "In production, you'll also handle Z"
Common Failures
| Failure | Fix |
|---|
| Wall of code, then explanation | Interleave code and explanation |
| "First, let me explain the history of..." | Start with the problem, not the history |
| Assuming knowledge ("as you know...") | Either explain it or link to prerequisite |
| Magic numbers/values in examples | Use realistic, explained values |
| Only happy path | Show error handling |
| Abstract examples (Foo, Bar, Widget) | Concrete domains (User, Order, Payment) |
Quality Checklist
Structure:
Code:
Clarity:
Trust:
Anti-Patterns
| Pattern | Fix |
|---|
| "Simply do X" | Remove "simply" |
| "It's obvious that..." | Explain anyway |
| Screenshot-only instructions | Add text/code |
| Massive code dump | Break into pieces |
| "Exercise left to reader" | Show the solution |
| "See the docs" | Summarize key points |
5. System Documentation (Architecture Guides)
For comprehensive technical docs that capture the "what" and "why" of complex systems.
Documentation Process
- Discovery - Analyze codebase structure, dependencies, design patterns, data flows
- Structuring - Create logical hierarchy, plan progressive disclosure, establish terminology
- Writing - Executive summary first, then high-level architecture to implementation details
Key Sections to Include
| Section | Purpose |
|---|
| Executive Summary | One-page overview for stakeholders |
| Architecture Overview | System boundaries, components, interactions |
| Design Decisions | Rationale behind architectural choices |
| Core Components | Deep dive into each major module/service |
| Data Models | Schema design and data flow |
| Integration Points | APIs, events, external dependencies |
| Deployment Architecture | Infrastructure and operational considerations |
| Performance Characteristics | Bottlenecks, optimizations, benchmarks |
| Security Model | Authentication, authorization, data protection |
System Docs Best Practices
- Always explain the "why" behind design decisions
- Use concrete examples from the actual codebase
- Create mental models that help readers understand the system
- Document both current state and evolutionary history
- Include troubleshooting guides and common pitfalls
- Provide reading paths for different audiences (developers, architects, operations)
Reference
