mcpField
T
technical-writer

technical-writer

github.com/curiositechDocuments257211 installsUpdated 3d ago
Repository

About technical-writer

A technical documentation skill for developers who need tutorials, guides, explanations, references, and operational docs. It applies the Diátaxis framework and emphasizes tested examples, troubleshooting, and completeness checks.

Key features

  1. 01Diátaxis-based document types
  2. 02Templates for README, ADR, API, and runbooks
  3. 03Guidance on tested code examples
  4. 04Troubleshooting and completeness checks
  5. 05Documentation validation script

Use cases

  1. 01Planning documentation for a software project
  2. 02Writing API references or operational runbooks
  3. 03Reviewing docs for broken links and missing steps

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/curiositech/some_claude_skills --skill technical-writer

After installing, type/technical-writerin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

CHANGELOG.md
.claude-plugin/
plugin.json
references/
adr-template.md
api-reference-template.md
readme-template.md
runbook-template.md
scripts/
validate-docs.sh

Details

From the project README

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

Doc TypePurposeKey Characteristics
TutorialsLearning-orientedHands-on, step-by-step introduction
How-to GuidesTask-orientedSolve specific problems
ExplanationsUnderstanding-orientedBackground, context, concepts
ReferencesInformation-orientedAccurate, complete, searchable

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/:

TemplateUse Case
readme-template.mdProject README with all essential sections
adr-template.mdArchitecture Decision Records
api-reference-template.mdREST API documentation
runbook-template.mdOperational procedures

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

Comments

Markdown supported