# Technical Writing

> This skill should be used when the user asks to "write blog post", "technical article", "tutorial", "explain concept", or needs guidance on technical writing for external audiences. Provides patterns for technical blogs and articles in both English and Japanese. Use when this capability is needed.

- Skill: `tomevault-io/technical-writing-4` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/technical-writing-4`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/technical-writing-4/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/technical-writing-4

---


# Technical Writing

Patterns for technical blogs and articles for external audiences.

## Article Types

| Type | Audience | Length | Structure |
|------|----------|--------|-----------|
| Tutorial | Learners | 1500-3000 | Problem -> Steps -> Example -> Troubleshooting |
| Concept | Understanding seekers | 1000-2500 | Hook -> Core -> Examples -> Misconceptions |
| Comparison | Decision makers | 1500-2500 | Criteria -> Options -> Features -> Recommendation |
| Case Study | Leaders | 1500-3000 | Challenge -> Solution -> Results -> Lessons |
| Opinion | Experienced devs | 800-1500 | Thesis -> Arguments -> Counterarguments -> Action |

## Core Principles

- **Hook early**: Problem statement, surprising fact, or relatable story in first paragraph
- **Inverted pyramid**: Lead with conclusion, most important info first
- **Show don't tell**: Working code, diagrams, before/after comparisons
- **One idea per section**: Split if covering multiple ideas
- **Respect reader time**: Be concise, provide TL;DR for long articles

## Title Patterns

- **How-to**: "How to Implement Rate Limiting with Redis"
- **Number list**: "5 Things Every Developer Should Know About TypeScript Generics"
- **Comparison**: "REST vs GraphQL: Which Should You Choose in 2025?"
- **Problem-solution**: "Solving N+1 Queries with DataLoader"
- **Deep dive**: "Understanding React Reconciliation: A Deep Dive"
- **Lessons**: "What I Learned Building a Real-Time Collaboration System"

## Language Guidelines

**English:**
- Conversational but professional
- First person ("I found...") or second person ("You can...")
- Vary sentence length

**Japanese:**
- Technical articles: です・ます調
- Personal blogs: flexible
- English technical terms as katakana where appropriate

## Writing Workflow

1. **Ideation**: Core message (one sentence), audience, article type
2. **Outline**: Section headings, key points, examples needed
3. **Draft**: Body first (not intro), include tested code, transitions
4. **Edit**: Read aloud, cut 20%, verify claims, check code
5. **Polish**: Proofread, optimize title/headings, add meta description

## Best Practices

**Critical:**
- Start with compelling hook, never "In this article..."
- Test all code examples before publishing
- Verify all technical claims

**High:**
- Explain code context before/after snippets
- Support claims with evidence (benchmarks, examples)
- Each section has one clear purpose

## Anti-Patterns

| Avoid | Instead |
|-------|---------|
| Burying the lede | Most important point first |
| Assuming motivation | Explain why reader should care |
| Code without context | Explain purpose before/after |
| Unsubstantiated claims | Benchmarks or reasoned arguments |
| Clickbait title | Title matches content scope |
| Wall of code | Break up with explanations |
| Generic intro | Hook that captures attention |

## Constraints

**Must:**
- Verify all technical claims
- Test all code examples
- Write for target audience level

**Avoid:**
- Jargon without explanation
- Untested code examples
- Overly complex explanations

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/motoki317) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->