Curiositech Some Claude Skills Technical Writer

Technical Writer

Expert technical documentation specialist focusing on developer documentation, API references, system architecture docs, runbooks, and knowledge base articles.

Quick Start

1. Identify doc type using Diátaxis: Tutorial, How-to, Explanation, or Reference
2. Know your audience - what they know, what they need to accomplish
3. Start with structure - outline before writing, use templates
4. Include working examples - all code must be tested and runnable
5. Add troubleshooting - anticipate common problems
6. Validate completeness - links work, steps accurate, nothing assumed

Core Capabilities

Diátaxis Framework

              PRACTICAL                    THEORETICAL
        ┌──────────────────────┬──────────────────────┐
LEARNING│     TUTORIALS        │    EXPLANATIONS      │
        │  "Learning by doing" │  "Understanding why" │
        ├──────────────────────┼──────────────────────┤
WORKING │    HOW-TO GUIDES     │     REFERENCE        │
        │  "Solve problems"    │  "Look up facts"     │
        └──────────────────────┴──────────────────────┘

Reference Templates

Complete templates in ./references/:

Anti-Patterns (10 Critical Mistakes)

1. Wall of Text

Symptom: Dense paragraphs, no headings or visual breaks Fix: Headings, bullet points, tables, code blocks, whitespace

2. Outdated Examples

Symptom: Code samples that don't compile or use deprecated APIs Fix: Test all examples in CI, version-lock dependencies, add "last verified" dates

3. Missing Prerequisites

Symptom: Tutorials assume knowledge/setup without stating it Fix: List prerequisites upfront, link to setup guides, specify versions

4. Expert Blindness

Symptom: Skipping "obvious" steps that aren't obvious to beginners Fix: Have newcomers test docs, include all steps, explain the "why"

5. No Error Guidance

Symptom: Happy path only, no troubleshooting Fix: Include common errors and solutions, link to support channels

6. Broken Links

Symptom: 404s to moved or deleted pages Fix: Link checking in CI, relative links where possible, redirects for moved content

7. Inconsistent Formatting

Symptom: Different styles, code block languages, heading levels Fix: Style guide, linting (markdownlint), templates for common doc types

8. Missing Context

Symptom: Docs assume reader knows system architecture Fix: Brief context at top, link to architecture docs, explain "where this fits"

9. Stale Screenshots

Symptom: UI screenshots from 3 versions ago Fix: Automate screenshot capture, note UI version, prefer text over images

10. No Versioning

Symptom: Docs don't match user's installed version Fix: Version selector, version badges, maintain docs per major version

Quality Checklist

Structure:

• Follows Diátaxis framework (tutorial/how-to/explanation/reference)
• Appropriate for target audience level
• Consistent formatting and style
• Updated table of contents

Content:

• Code examples are tested and runnable
• All links work (no 404s)
• Version information where relevant
• Includes troubleshooting section

Completeness:

• Prerequisites listed upfront
• All steps included (no expert blindness)
• Error scenarios covered
• Related documentation linked

Validation Script

Run ./scripts/validate-docs.sh to check:

• README completeness
• Documentation structure
• ADR format compliance
• Broken links
• Common documentation issues

Documentation Tools

Static Sites: Docusaurus, MkDocs, VitePress, Astro API Docs: Swagger/Redoc, Stoplight, ReadMe.io Diagrams: Mermaid, PlantUML, Excalidraw, Diagrams.net

External Resources

• Diátaxis Framework
• Google Developer Documentation Style Guide
• Write the Docs
• Keep a Changelog
• ADR GitHub

Converted and distributed by TomeVault — claim your Tome and manage your conversions.