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

1. Lead with clear definition paragraph
2. Use bullet points for key characteristics
3. Separate sections with --- dividers
4. Include info boxes and warnings where needed
5. Link to related API reference
6. 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:

1. Understand the documentation type - Functional guide vs API reference
2. Load relevant skills - Writing patterns for the document type
3. 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.