Using Ring Technical Writing Specialists

The ring-tw-team plugin provides specialized agents for technical documentation. Use them via Task tool with subagent_type:.

Remember: Follow the ORCHESTRATOR principle from ring:using-ring. Dispatch agents to handle documentation tasks; don't write complex documentation directly.

3 Documentation Specialists

| Agent | Specialization | Use When | |-------|---------------|----------| | ring:functional-writer | Conceptual docs, guides, tutorials, best practices, workflows | Writing product guides, tutorials, "how to" content | | ring:api-writer | REST API reference, endpoints, schemas, errors, field descriptions | Documenting API endpoints, request/response examples | | ring:docs-reviewer | Voice/tone, structure, completeness, clarity, accuracy | Reviewing drafts, pre-publication quality check |

Documentation Standards Summary

Voice and Tone

Assertive, but never arrogant – Say what needs to be said, clearly
Encouraging and empowering – Guide users through complexity
Tech-savvy, but human – Use technical terms when needed, prioritize clarity
Humble and open – Confident but always learning

Capitalization

Sentence case for all headings and titles
Only first letter and proper nouns capitalized
✅ "Getting started with the API"
❌ "Getting Started With The API"

Structure Patterns

Lead with clear definition paragraph
Use bullet points for key characteristics
Separate sections with --- dividers
Include info boxes and warnings where needed
Link to related API reference
Add code examples for technical topics

Dispatching Specialists

Parallel dispatch for comprehensive documentation (single message, multiple Tasks):

Task #1: functional-writer (write the guide)
Task #2: api-writer (write API reference)
(Both run in parallel)

Then:
Task #3: docs-reviewer (review both)

Available in This Plugin

Agents: functional-writer, api-writer, docs-reviewer

Skills:

using-tw-team: Plugin introduction
writing-functional-docs: Functional doc patterns
writing-api-docs: API reference patterns
documentation-structure: Hierarchy and organization
voice-and-tone: Voice guidelines
documentation-review: Quality checklist
api-field-descriptions: Field description patterns

Commands:

/write-guide: Start functional guide
/write-api: Start API documentation
/review-docs: Review existing docs

Integration with Other Plugins

| Plugin | Use For | |--------|---------| | ring:using-ring (default) | ORCHESTRATOR principle | | ring:using-dev-team | Developer agents for technical accuracy | | ring:using-pm-team | Pre-dev planning before documentation |

ORCHESTRATOR Principle

You're the orchestrator – Dispatch specialists, don't write directly
Let specialists apply standards – They know voice, tone, structure
Combine with other plugins – API writers + backend engineers for accuracy

✅ "I need documentation for the new feature. Let me dispatch functional-writer."

❌ "I'll manually write all the documentation myself."

Standards Loading (MANDATORY)

Before dispatching any documentation agent:

Understand the documentation type - Functional guide vs API reference
Load relevant skills - Writing patterns for the document type
Verify prerequisites - Product knowledge, terminology, audience

HARD GATE: MUST dispatch appropriate specialist (not write directly).

Blocker Criteria - STOP and Report

| Condition | Decision | Action | |-----------|----------|--------| | Documentation type unclear | STOP | Report: "Need to clarify functional guide vs API reference" | | No subject matter source | STOP | Report: "Need source material or SME access" | | Audience undefined | STOP | Report: "Need target audience definition" | | Product not yet defined | STOP | Report: "Cannot document undefined features" |

Cannot Be Overridden

These requirements are NON-NEGOTIABLE:

MUST dispatch specialist agents (not write directly)
MUST use appropriate agent for document type
MUST follow ORCHESTRATOR principle
CANNOT skip documentation review before publication
CANNOT mix agent responsibilities

Severity Calibration

| Severity | Criteria | Examples | |----------|----------|----------| | CRITICAL | Writing directly instead of dispatching | Orchestrator writes full documentation | | HIGH | Wrong agent for document type | Using api-writer for conceptual guide | | MEDIUM | Skipping review step | Publishing without docs-reviewer check | | LOW | Suboptimal agent combination | Could parallelize dispatches |

Pressure Resistance

| User Says | Your Response | |-----------|---------------| | "Just write the docs quickly, no need for specialists" | "MUST dispatch specialists. They apply consistent standards. I'll dispatch the appropriate agent." | | "Skip the review, we're in a hurry" | "Documentation review is REQUIRED before publication. I'll dispatch docs-reviewer." | | "One agent can do it all" | "Each agent has specialized knowledge. I'll dispatch the correct specialist for each document type." | | "README is enough documentation" | "README is an entry point, not complete documentation. I'll dispatch agents for proper docs." | | "Developers can figure it out from the code" | "Code is NOT documentation. MUST create proper documentation. I'll dispatch the appropriate writers." |

Anti-Rationalization Table

| Rationalization | Why It's WRONG | Required Action | |-----------------|----------------|-----------------| | "Simple docs, I can write directly" | Simple ≠ no standards. Specialists ensure consistency | MUST dispatch specialist | | "Faster to write myself" | Speed without quality creates tech debt | Dispatch agents, ensure quality | | "Already know the product well" | Knowledge ≠ documentation skill | Use specialists for writing | | "Review takes too long" | Review catches issues before users do | MUST include review step | | "Documentation isn't critical path" | Documentation IS part of the feature | Treat docs as required deliverable | | "Internal docs don't need standards" | Internal users deserve quality too | Apply same standards everywhere |

When This Skill is Not Needed

Signs that documentation workflow is already correct:

Appropriate specialist dispatched for each document type
ORCHESTRATOR principle followed (not writing directly)
Documentation review included in workflow
Parallel dispatch used for efficiency
Clear handoffs between agents

If all above are true: Workflow is correct, proceed with dispatches.