playbooks

home / skills / eddiebe147 / claude-settings / technical-writer

technical-writer skill

/skills/technical-writer

This skill transforms complex technical concepts into clear API documentation, user guides, and READMEs that balance accuracy with readability.

npx playbooks add skill eddiebe147/claude-settings --skill technical-writer

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
4.7 KB
---
name: Technical Writer
slug: technical-writer
description: Create clear, accurate technical documentation for developers and end users
category: writing
complexity: complex
version: "1.0.0"
author: "ID8Labs"
triggers:
  - "write documentation"
  - "create docs"
  - "technical writing"
  - "api documentation"
  - "user guide"
tags:
  - documentation
  - api-docs
  - user-guides
  - technical-communication
---

# Technical Writer

Transform complex technical concepts into clear, accessible documentation that helps users succeed. This skill specializes in creating API documentation, user guides, README files, tutorials, and reference materials that balance technical accuracy with readability.

Whether you're documenting code libraries, software products, system architectures, or processes, this skill ensures your documentation is comprehensive, well-organized, and genuinely helpful. It follows industry best practices for structure, formatting, and content organization.

Ideal for software developers, DevOps engineers, product managers, and technical teams who need to create documentation that both technical and non-technical audiences can understand and use effectively.

## Core Workflows

### Workflow 1: API Documentation
1. **Analyze Codebase** - Review API endpoints, parameters, responses
2. **Structure Reference** - Organize by resource/endpoint with consistent formatting
3. **Document Endpoints** - Write clear descriptions, parameters, request/response examples
4. **Add Code Samples** - Include examples in multiple languages
5. **Create Quick Start** - Write getting-started guide with authentication
6. **Build Error Reference** - Document error codes and troubleshooting
7. **Generate OpenAPI Spec** - Create machine-readable API specification

### Workflow 2: User Guide Creation
1. **Audience Analysis** - Identify user personas and skill levels
2. **Task Mapping** - List all user tasks and workflows
3. **Content Outline** - Structure guide by user journey, not features
4. **Write Procedures** - Create step-by-step instructions with screenshots
5. **Add Context** - Explain why and when, not just how
6. **Build Navigation** - Create clear TOC, index, and search keywords
7. **Test Documentation** - Validate against real user scenarios

### Workflow 3: README Excellence
1. **Project Overview** - One-paragraph description of what it does
2. **Installation** - Clear setup instructions with prerequisites
3. **Quick Start** - Minimal example to get running fast
4. **Usage Examples** - Real-world code samples with explanations
5. **Configuration** - Document all options, environment variables, flags
6. **Contributing** - Guidelines for contributions and development setup
7. **License & Credits** - Legal info and acknowledgments

### Workflow 4: Architecture Documentation
1. **System Overview** - High-level diagram and description
2. **Component Breakdown** - Detail each major component and responsibility
3. **Data Flow** - Document how information moves through system
4. **Deployment** - Infrastructure, scaling, monitoring considerations
5. **Security Model** - Authentication, authorization, data protection
6. **Decision Records** - Document architectural decisions and rationale

## Quick Reference

| Action | Command/Trigger |
|--------|-----------------|
| Create API docs | "Document this API" |
| Write README | "Create README for this project" |
| User guide | "Write user guide for [feature]" |
| Troubleshooting section | "Create troubleshooting guide" |
| Tutorial | "Write tutorial for [task]" |
| Release notes | "Generate release notes from changes" |
| Migration guide | "Write migration guide to [version]" |
| Code comments | "Document this code" |

## Best Practices

- **Start with why** - Explain purpose and use cases before diving into details
- **Show working examples** - Every concept needs a concrete code sample
- **Be consistent** - Use same terminology, formatting, and structure throughout
- **Write for scanning** - Use headers, lists, tables, and code blocks liberally
- **Test everything** - Validate all code examples actually work
- **Version clearly** - Mark which version each feature/behavior applies to
- **Update proactively** - Keep docs in sync with code changes
- **Link strategically** - Connect related concepts without overwhelming
- **Use diagrams** - Complex flows need visual representation
- **Maintain searchability** - Optimize for ctrl+F and site search
- **Provide context** - Include when/why to use something, not just how
- **Handle errors gracefully** - Document common errors and solutions
- **Write for internationalization** - Use clear, simple language that translates well
- **Include prerequisites** - Never assume prior knowledge
- **Offer quick wins** - Give users success in under 5 minutes

Overview

This skill creates clear, accurate technical documentation for developer and end-user audiences. It produces API references, user guides, READMEs, tutorials, architecture docs, and troubleshooting materials that balance precision with readability. The output follows industry best practices for structure, examples, and maintainability.

How this skill works

I analyze the codebase, APIs, and product workflows to identify what needs documenting and for whom. Then I organize content by user journey or resource, write step-by-step procedures and reference sections, add runnable code samples and diagrams, and produce machine-readable artifacts like OpenAPI where appropriate. I validate examples and recommend navigation, versioning, and testing strategies to keep docs accurate over time.

When to use it

  • Publishing or updating an API reference for partners or public users
  • Creating a README and quick-start for a new or existing project
  • Producing a user guide or tutorial for a feature or workflow
  • Documenting system architecture, deployment, and security decisions
  • Preparing migration guides, release notes, or troubleshooting content

Best practices

  • Start with why: explain purpose and common use cases before details
  • Provide working, copy-paste code samples and quick-starts
  • Structure for scanning: use concise headings, lists, tables, and examples
  • Validate examples and test procedures against real scenarios
  • Version and date docs clearly and keep them synchronized with code
  • Include prerequisites, error handling, and short troubleshooting steps

Example use cases

  • Generate a complete REST API reference with endpoint descriptions, parameters, examples, and OpenAPI spec
  • Write a README with install steps, a minimal quick-start, usage examples, configuration options, and contribution guidelines
  • Create a user guide that maps tasks to step-by-step procedures, screenshots, and contextual tips
  • Document system architecture: high-level diagram, component responsibilities, data flow, deployment and security considerations
  • Produce a migration guide or release notes summarizing breaking changes, upgrade steps, and remediation tips

FAQ

Can you produce code examples in multiple languages?

Yes. I include examples in languages you specify and ensure they are runnable and idiomatic where possible.

How do you handle versioning and updates?

I mark which version each section applies to, recommend a release process for docs, and can generate diffs or change logs to keep documentation in sync with code.