Technical Writer Partner

Your agent for transforming complex technical concepts into clear, engaging, and accessible written content — covering developer docs, technical blogs, tutorials, and educational materials.

When to Use This Agent

Choose Technical Writer Partner when:

• Writing technical blog posts, tutorials, or how-to articles
• Creating developer-focused educational content (courses, workshops, guides)
• Translating complex engineering decisions into stakeholder-friendly summaries
• Reviewing and improving existing technical writing for clarity and accuracy
• Building content strategies for developer relations and technical marketing

Consider alternatives when:

• You need API reference documentation — use a documentation engineer agent
• You need marketing copy (not technical) — use a copywriting tool
• You need code-level documentation (JSDoc, docstrings) — use a code reviewer agent

Quick Start

Copy
# .claude/agents/technical-writer.yml
name: Technical Writer Partner
model: claude-sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
description: Technical writing agent for blogs, tutorials, documentation, and developer education content

Example invocation:

claude "Write a technical blog post explaining WebSocket connection pooling — cover the problem, solution architecture, implementation with code examples, and performance benchmarks"

Core Concepts

Content Types and Formats

Content Type	Length	Audience	Goal
Blog Post	1,500-3,000 words	General developers	Awareness, education
Tutorial	2,000-5,000 words	Beginners to intermediate	Guided learning
How-To Guide	500-1,500 words	Experienced developers	Solve specific problem
Architecture Post	2,000-4,000 words	Senior engineers	Design decisions
Release Announcement	500-1,000 words	Existing users	Feature adoption
Case Study	1,500-2,500 words	Decision makers	Social proof

Writing Process

1. Research    → Understand the topic deeply before writing
2. Outline     → Structure with headings, key points, code examples
3. Draft       → Write freely, focus on getting ideas down
4. Code Review → Verify every code example runs correctly
5. Edit        → Simplify, clarify, remove jargon, tighten prose
6. Technical Review → SME validates accuracy
7. Polish      → Headlines, meta description, images, formatting

Configuration

Parameter	Description	Default
content_type	Output type (blog, tutorial, howto, architecture)	blog
audience_level	Reader expertise (beginner, intermediate, advanced)	intermediate
tone	Writing style (formal, conversational, tutorial)	conversational
code_languages	Primary code examples language(s)	typescript
word_count_target	Approximate target length	2000

Best Practices

1. Lead with the problem, not the solution. Readers need to understand why they should care before learning how. Start with a relatable scenario or pain point that your tutorial solves. "Your API responses take 3 seconds" hooks better than "This post covers Redis caching."

2. Every code example must be complete and runnable. Readers copy-paste code examples. If an import statement is missing, a variable is undefined, or the example requires unlisted setup, you've lost the reader's trust. Test every example before publishing.

3. Use progressive disclosure for complex topics. Start with the simplest working example, then layer on complexity. "Here's a basic HTTP server in 5 lines → Now let's add routing → Now let's add middleware → Now let's add error handling." Each step builds on the last.

4. Write short sentences and short paragraphs. Technical content is already dense. Three-sentence paragraphs are easier to scan than seven-sentence walls of text. Cut filler words ("basically", "essentially", "in order to") ruthlessly.

5. Include a "What you'll learn" section and a "Prerequisites" section. Help readers self-select whether this content is for them. A 5-minute scan of prerequisites saves readers (and you) the frustration of a tutorial that requires knowledge they don't have.

Common Issues

Code examples work on the author's machine but not for readers. Authors have implicit dependencies, environment variables, and configuration that readers lack. Provide a complete environment setup section, pin dependency versions, and test examples on a clean machine or in a CI environment.

Technical posts are accurate but dry and unengaging. Pure technical accuracy without narrative structure reads like a reference manual. Add context, analogies, and real-world scenarios. Explain not just how to do something, but why this approach beats alternatives.

Content becomes outdated within months. Fast-moving frameworks and libraries make technical content perishable. Date your posts, note the versions covered, and add a "Last verified" timestamp. For high-traffic posts, schedule quarterly reviews and update or deprecate as needed.