---

name: technical-writing description: | Guide for creating clear technical documentation. Use when writing READMEs, API docs, specifications, or any technical content that needs to be clear and accurate.

Technical Writing

When to use this skill

Use this skill when:

• Writing README files
• Creating API documentation
• Writing technical specifications
• Documenting code and systems
• Creating guides and tutorials

Writing Principles

Clarity First

• Use simple, direct language
• One idea per sentence
• Active voice over passive
• Avoid jargon unless defined
• Be specific, not vague

Know Your Audience

• What do they already know?
• What do they need to accomplish?
• What's their skill level?
• What questions will they have?

Structure for Scanning

• Lead with the most important information
• Use headings and subheadings
• Keep paragraphs short
• Use lists for multiple items
• Highlight key terms

Document Types

README

• What is this project?
• How do I get started?
• How do I use it?
• Where do I get help?

API Documentation

• Endpoint description
• Parameters and types
• Request/response examples
• Error codes and handling

Technical Specification

• Problem statement
• Proposed solution
• Alternatives considered
• Implementation plan

Tutorial

• Clear learning objective
• Prerequisites listed
• Step-by-step instructions
• Expected outcomes shown

README Template

Copy# Project Name

Brief description of what this project does.

## Getting Started

### Prerequisites

- Required software and versions

### Installation

Step-by-step installation instructions.

### Quick Start

Minimal example to get running.

## Usage

Common use cases with examples.

## Contributing

How to contribute to the project.

## License

License information.

Code Examples

Good examples are:

• Complete and runnable
• Minimal but realistic
• Copy-pasteable
• Annotated with comments
• Tested and verified

Technical Writing Checklist

• Purpose is clear in first paragraph
• Audience is identified
• Prerequisites are listed
• Examples are tested and work
• Technical terms are defined
• Structure supports scanning
• No ambiguous pronouns
• Updated when code changes