technical-writing

name	Technical Writing
description	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.
version	0.1.0

Provide structured patterns for writing technical blogs and articles that effectively communicate technical concepts to external audiences. Write Read Edit WebSearch mcp__context7__resolve-library-id mcp__context7__get-library-docs Step-by-step guide to accomplish a specific task Developers learning a new skill

Problem statement / What you'll learn

Prerequisites

Step-by-step instructions

Complete working example

Troubleshooting common issues

Next steps / Further reading

1500-3000 words Deep dive into a technical concept Developers seeking understanding

Hook / Why this matters

Core concept explanation

Analogies and visualizations

Practical examples

Common misconceptions

When to use / When to avoid

1000-2500 words Compare technologies, approaches, or tools Developers making technical decisions

Context and criteria

Overview of each option

Feature-by-feature comparison

Benchmark results (if applicable)

Use case recommendations

Conclusion with clear guidance

1500-2500 words Real-world implementation story Developers and technical leaders

Background and challenge

Solution approach

Implementation details

Results and metrics

Lessons learned

Recommendations

1500-3000 words Technical opinion or best practices Experienced developers

Thesis statement

Supporting arguments with evidence

Counterarguments addressed

Practical implications

Call to action

800-1500 words

<writing_principles> Capture attention in the first paragraph Start with a problem the reader faces Use a surprising fact or statistic Tell a brief relatable story

Each section should have a single clear purpose If a section covers multiple ideas, split it Use headings that summarize the key point Demonstrate concepts with examples Include working code snippets Use diagrams for architecture Show before/after comparisons Be concise, get to the point Lead with the conclusion Use bullet points for lists Provide TL;DR for long articles Build trust through accuracy and honesty Cite sources and benchmarks Acknowledge limitations Show your work (methodology)

<language_guidelines>

Conversational but professional

Confident, helpful, peer-to-peer First person ("I found that...") or second person ("You can...") <sentence_length>Vary between short and medium</sentence_length> Overly formal academic language, buzzwords without substance

読者との対話を意識した文体 専門的だが親しみやすい 技術記事: です・ます調、個人ブログ: 柔軟に 過度に硬い表現、主語の省略による曖昧さ 英語の技術用語は適度にカタカナで使用可 Adapt style to each language's conventions (not literal translation) Keep technical terms consistent Adjust examples for cultural relevance when appropriate Identify the core message (one sentence) Define target audience and their current knowledge Choose article type Research existing content on the topic Draft section headings Note key points for each section Identify examples and code snippets needed Estimate length Write the body first (not the introduction) Include all code examples and test them Add transitions between sections Write introduction and conclusion last Read aloud for flow Cut unnecessary words (aim for 20% reduction) Verify all technical claims Check code examples compile/run Add/improve diagrams if helpful Proofread for typos and grammar Optimize title and headings for clarity Add meta description for SEO Prepare social media summary - Type: [tutorial/concept/comparison/case_study/opinion] - Audience: [beginner/intermediate/advanced developers] - Core message: [one sentence] - Language: [en/ja/both] - Target length: [word count] [Section headings with key points] [Article content] - [ ] Hook is compelling - [ ] Each section has one clear purpose - [ ] Code examples tested and working - [ ] Technical claims verified - [ ] Read aloud for flow - [ ] Trimmed unnecessary words - [ ] Title and headings optimized

<title_patterns> How to [achieve result] with [tool/technique] How to Implement Rate Limiting with Redis [N] [Things] Every Developer Should Know About [Topic] 5 Things Every Developer Should Know About TypeScript Generics [A] vs [B]: Which Should You Choose in [Year]? REST vs GraphQL: Which Should You Choose in 2025? Solving [Problem] with [Solution] Solving N+1 Queries with DataLoader Understanding [Concept]: A Deep Dive Understanding React Reconciliation: A Deep Dive What I Learned [Building/Using] [Thing] What I Learned Building a Real-Time Collaboration System </title_patterns>

<best_practices> Start with a compelling hook in the first paragraph Use a problem the reader faces, a surprising fact, or a brief relatable story Put the most important point first using inverted pyramid structure Lead with the conclusion, provide TL;DR for long articles Test all code examples before publishing Verify code compiles, runs, and produces expected output Explain code context before or after each snippet Describe what the code does and why it's written that way Support claims with evidence Include benchmarks, examples, or reasoned arguments for technical claims Each section should have one clear purpose Split sections covering multiple ideas, use headings that summarize the key point Use diagrams for architectural concepts Include visual representations to complement text explanations Vary sentence length for readability Mix short and medium sentences to maintain reader engagement Adapt style to language conventions Use conversational but professional tone in English, です・ます調 in Japanese technical articles </best_practices>

<anti_patterns> Hiding the main point deep in the article Put the most important point first, use inverted pyramid structure Not explaining why the topic matters Explain why the reader should care early in the article Showing code without explaining its purpose Explain what code does and why before or after the snippet Making claims like "X is the best" without evidence Support claims with benchmarks, examples, or reasoned arguments Title promises more than content delivers Ensure title accurately reflects content and scope Long code blocks without explanation Break up code with explanations, highlight key lines, add comments Starting with "In this article..." or similar phrases Start with a hook that captures attention immediately </anti_patterns>