Tech Writer Researcher

Technical Writer / Researcher

Overview

Write and research technical documentation. This skill covers information architecture, style guides, API documentation, user research, content strategy, and documentation operations.

Features

• Information architecture: content modeling, navigation design, taxonomy creation
• Style guides: voice and tone, terminology, code examples, accessibility standards
• API documentation: endpoint reference, request/response examples, authentication guides
• User research: persona development, usability testing, content gap analysis
• Content strategy: editorial calendars, content audits, migration planning
• Documentation operations: version control, review workflows, localization, metrics

Usage

1. Identify the user's technical writing need (architecture, style, API docs, research, or strategy) 2. Follow the corresponding workflow below 3. Produce structured outputs: content models, style guides, API reference docs, research reports, or content strategies

Examples

• User: "Write API documentation"

Agent: Runs API Documentation workflow, creates endpoint reference with request/response examples, authentication guide, and error codes

• User: "Create a style guide"

Agent: Runs Style Guide workflow, defines voice and tone, establishes terminology, produces code example standards

• User: "Audit our documentation"

Agent: Runs Content Strategy workflow, analyzes content gaps, identifies outdated pages, produces improvement roadmap

When to Use

• Authoring API references, tutorials, runbooks, READMEs, and release notes
• Planning documentation information architecture and content lifecycle
• Conducting structured research, literature reviews, and evidence synthesis
• Editing for clarity, consistency, accessibility, and style-guide compliance

When NOT to Use

• Prompt/LLM agent design, eval harnesses, or guardrails → use prompt-engineer
• Business requirements, BRDs, or process modeling for delivery projects → use business-analyst
• Warehouse SQL optimization or dimensional modeling → use data-warehouse-engineer
• Revenue accounting, close calendars, or ASC 606 judgments → use senior-revenue-accountant
• Customer ticket repro, escalation, support KB fixes → use support-engineer
• Product support how-tos, macros, ticket triage → use product-support-specialist
• Strategy consulting, executive recommendations, operating model → use business-consultant
• Business model and competitive monetization research → use business-model-researcher
• All-hands, crisis statements, launch messaging → use communication-lead
• Developer learning paths, workshops, certification programs → use developer-education-lead

Core Workflows

1. Technical Documentation Workflow

Phase checklist:

1. Audience analysis

• Who reads this? (role, skill level, context)
• What do they need to do after reading?
• What do they already know vs. need to learn?

2. Information gathering

• Interview SMEs (subject matter experts)
• Review existing docs, code, and specs
• Test the product/feature yourself

3. Structure & outline

• Choose document type (see table below)
• Create heading hierarchy
• Identify prerequisites and next steps

4. Draft

• Write for clarity first, polish later
• Include code examples, screenshots, diagrams
• Use consistent terminology

5. Review

• Technical accuracy review (SME)
• Editorial review (style, grammar, clarity)
• User testing (if possible)

6. Publish & maintain

• Version control and changelog
• Feedback mechanism
• Scheduled review cadence

Document type selection:

2. Research & Synthesis Workflow

Structured research process:

1. Define the question

• Convert vague request into specific research question
• Identify scope (time period, geography, sources)
• Define success criteria (decision support, background, deep dive)

2. Source & collect

• Primary: interviews, surveys, observations
• Secondary: papers, reports, databases, news
• Tertiary: summaries, reviews, meta-analyses

3. Evaluate sources

• Currency, relevance, authority, accuracy, purpose (CRAAP test)
• Bias detection (funding, affiliation, methodology)

4. Synthesize

• Group findings by theme
• Identify agreements, contradictions, gaps
• Extract evidence-backed conclusions

5. Communicate

• Match format to audience (executive summary, full report, memo)
• Cite sources properly
• Include confidence levels and limitations

3. Content Strategy & Planning

Content inventory template:

4. Editing & Review

Self-editing checklist:

• [ ] One idea per paragraph
• [ ] Active voice (where appropriate)
• [ ] Defined acronyms on first use
• [ ] Consistent terminology
• [ ] Scannable headings and lists
• [ ] Working links and code examples
• [ ] Accessibility (alt text, color independence)

Content Strategy

Audience Analysis

Persona Template

## [Persona Name]

**Role:** Senior Developer at mid-size SaaS company
**Goals:** Evaluate if our API fits their integration needs
**Pain points:** Poor examples, unclear error messages, missing edge case docs
**Technical level:** Expert in their stack, beginner with our tech
**Context:** Evaluating during sprint planning, limited time
**Preferred format:** Copy-paste code examples, decision trees

**Quote:** "I just need to see if this handles webhooks properly."

Audience Matrix

Content Planning

Content Calendar Template

Content Prioritization

Score each piece by:

• Reach: How many users affected?
• Impact: How critical is this information?
• Effort: Time to produce?
• Urgency: Is there a deadline or blocker?

Documentation Lifecycle

States

Review Cadence

Content Metrics

Information Scent

Help users know they're in the right place:

• Page title matches search query
• First paragraph confirms relevance
• Headings preview what's covered
• Cross-links to related content

Content Reuse Strategy

Single Sourcing

Write once, publish everywhere:

• Source in Markdown/DITA
• Generate docs site, PDF, help center
• Include in product (in-app help)

Snippet Libraries

Maintain reusable content:

• Warnings and disclaimers
• Common troubleshooting steps
• Boilerplate definitions
• Code examples by language

Governance

RACI for Documentation

Style Guide Governance

• Versioned style guide in repo
• Linting with Vale or similar
• Annual review for relevance
• Contribution process for additions

Multichannel Publishing

Research Methods

Research Design Frameworks

PICO (Evidence-Based Practice)

Used for clinical/technical literature reviews:

• Population: Who or what is being studied?
• Intervention: What action or exposure?
• Comparison: What is the alternative?
• Outcome: What is measured?

Example: "In distributed systems (P), does chaos engineering (I) vs traditional testing (C) reduce production incidents (O)?"

SPIDER (Qualitative Research)

• Sample: Who was studied?
• Phenomenon: What was explored?
• Design: How was it studied?
• Evaluation: What were the outcomes?
• Research type: Qualitative/quantitative/mixed

Source Evaluation (CRAAP Test)

Research Types & When to Use

Synthesis Techniques

Thematic Analysis

1. Familiarize: read all sources thoroughly 2. Code: label interesting features systematically 3. Theme: collate codes into potential themes 4. Review: check themes against data 5. Define: name and define each theme 6. Write: produce coherent narrative

Evidence Matrix

Synthesis by Argument

Group findings by:

• Agreement: Multiple sources converge
• Disagreement: Contradictory findings (explore why)
• Gap: No research on specific sub-question
• Methodological issues: Limitations affecting interpretation

Citation & Reference Management

APA Style (Common for Research)

Book: Author, A. A. (Year). Title. Publisher.
Journal: Author, A. A. (Year). Title. Journal, vol(issue), pages.
Web: Author. (Year, Month Day). Title. Site. URL

IEEE Style (Technical/Engineering)

[1] A. Author, "Title of paper," in Title of Book, City, State, Country: Publisher, year, pp. xx-xx.

Chicago Style (Humanities/Business)

Author, Title (Place: Publisher, Year), page.

Reference Management Tools

Interview Techniques

SME Interview Structure

1. Context: What are we documenting and why? 2. Walkthrough: Show me how you do X 3. Edge cases: What can go wrong? 4. Audience: Who needs this and what do they know? 5. Validation: Can I follow up with a draft?

Active Listening for Writers

• Paraphrase to confirm understanding
• Ask "Why?" to get rationale, not just steps
• Capture exact terminology (don't translate yet)
• Record with permission, take verbatim notes

Competitive Analysis

Feature Comparison Matrix

Analysis Dimensions

• Product features and UX
• Pricing and packaging
• Market positioning and messaging
• Strengths, weaknesses, opportunities, threats
• Customer reviews and sentiment
• Technical architecture (if relevant)

Evidence Hierarchy

For technical research:

• Primary: RFCs, official documentation, source code
• Secondary: Books, peer-reviewed papers, conference talks
• Tertiary: Blog posts, tutorials, Stack Overflow

Bias Detection

Technical Writing

Document Templates

README Template

# Project Name

One-sentence description of what this project does.

## Installation

pip install package-name

## Quick Start

import package result = package.do_something()

## Documentation

Full docs: [link]

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md)

## License

[MIT](LICENSE)

API Reference Template

## GET /resource/{id}

Retrieve a single resource by ID.

### Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | Yes | Unique resource identifier |

### Response

{ "id": "abc123", "name": "Example", "created_at": "2024-01-15T10:00:00Z" }

### Errors
| Status | Description |
|---|---|
| 404 | Resource not found |
| 403 | Insufficient permissions |

Runbook Template

# [Incident Name] Runbook

## Symptoms
- [ ] Alert: `error_rate > 5%`
- [ ] User reports: [specific symptom]

## Impact Assessment
1. Check dashboard: [link]
2. Identify scope: [affected regions/services]

## Resolution Steps
1. [Step 1 with command]
2. [Step 2 with command]
3. Verify: [how to confirm fix]

## Rollback
If resolution fails:
1. [Rollback command]
2. [Verification]

## Post-Incident
- [ ] Update status page
- [ ] Log in incident tracker

Style Guide Principles

Clarity

• Use simple words: "use" not "utilize"
• Short sentences (<25 words)
• One idea per paragraph
• Front-load important information

Consistency

• Same term for same concept (don't alternate "user" and "customer")
• Same formatting for same elements (all code in backticks)
• Same voice throughout (active preferred for instructions)

Accessibility

• Alt text for all images
• Don't rely on color alone (add labels or patterns)
• Use descriptive link text (not "click here")
• Tables with headers for screen readers

Code Examples

• Complete, copy-paste runnable snippets
• Include expected output as comments
• Show error handling for non-trivial examples
• Update examples when API changes

Information Architecture

Diátaxis Framework

Structure docs by user need, not by feature:

Doc Site Structure

Getting Started/
  Installation
  Quick Start
  Configuration
Tutorials/
  Tutorial 1
  Tutorial 2
How-To Guides/
  Deploy
  Migrate
  Troubleshoot
Reference/
  API
  CLI
  Configuration
Explanation/
  Architecture
  Security
  Performance

Review Rubric

Common Anti-Patterns

Localization Basics

• Write for translation: avoid idioms, slang, cultural references
• Leave space for text expansion (30% for some languages)
• Don't concatenate strings: "Click" + "Save" → "Click Save"
• Use ICU message format for pluralization and variables
• Provide context for translators in comments

Tools & Frameworks

Markup Languages

Docs-as-Code Stack

Static Site Generators

Documentation Platforms

Linting & Quality

Vale configuration example (.vale.ini):

StylesPath = .github/styles
MinAlertLevel = suggestion

Packages = Google, write-good

[*.md]
BasedOnStyles = Vale, Google, write-good
Google.Headings = NO

Diagram Tools

Mermaid example:

graph TD
    A[User Request] --> B{Cache Hit?}
    B -->|Yes| C[Return Cached]
    B -->|No| D[Query Database]
    D --> E[Cache Result]
    E --> F[Return Data]

API Documentation

OpenAPI / Swagger

openapi: 3.0.0
info:
  title: Example API
  version: 1.0.0
paths:
  /users/{id}:
    get:
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

Code Annotation Tools

Research Tools

Version Control for Docs

Git Workflow for Documentation

main (published)
  └── develop (staging)
        └── feature/docs-update-123

Branch naming:

• docs/update-readme
• docs/api-version-2
• docs/fix-typo-getting-started

Commit conventions:

docs: update API reference for v2
docs: fix broken links in tutorial
docs: add troubleshooting section

Collaboration Workflows

Review Process

1. Writer creates PR with documentation changes 2. Automated checks (Vale, link checker, build) 3. SME review for accuracy (request or required) 4. Editor review for style and clarity 5. Merge and deploy (continuous or scheduled)

Feedback Collection

• In-page feedback widget ("Was this helpful?")
• GitHub issues with "documentation" label
• Slack/Discord channel for doc questions
• Quarterly user surveys

Accessibility Tools

Content Management