technical-writing_skill

Overview

This skill helps produce clear, accessible documentation for both technical and non-technical audiences. It focuses on practical examples, logical structure, and concise explanations so users can understand why features exist and how to use them. The result is documentation that reduces support load and improves onboarding success.

How this skill works

I analyze the target audience and required outcomes, then structure content from high-level purpose to step-by-step instructions. I convert complex concepts into simple language, add concrete code or command examples, and include troubleshooting steps for common errors. The output is organized with clear headings, callouts, and actionable examples.

When to use it

• Writing user guides, tutorials, or onboarding flows for software
• Creating README or quickstart sections for a project
• Documenting API endpoints, CLI commands, or configuration options
• Explaining architecture, design decisions, or complex workflows
• Adding troubleshooting and error explanation sections to reduce support requests

Best practices

• Start with the why, then show the how with minimal assumptions about prior knowledge
• Use active voice and short sentences; prefer concrete verbs like 'send', 'click', 'run'
• Include working code/examples and expected outputs for reproducibility
• Organize content with clear headings, steps, and summaries for quick scanning
• Add a troubleshooting section and common error explanations to speed problem resolution

Example use cases

• A quickstart guide that shows how to install, configure, and run a project in five steps
• API documentation that lists endpoints with example requests, responses, and common errors
• Feature documentation that explains purpose, usage scenarios, and sample workflows
• Migration notes that describe breaking changes, upgrade steps, and verification checks