130 lines
2.5 KiB
Markdown
130 lines
2.5 KiB
Markdown
---
|
|
name: write-guide
|
|
description: Start writing a functional guide with voice, tone, and structure guidance
|
|
argument-hint: "[topic]"
|
|
arguments:
|
|
- name: topic
|
|
description: The topic or feature to document
|
|
required: true
|
|
---
|
|
|
|
# Write Guide Command
|
|
|
|
You're starting a functional documentation task. Follow these steps:
|
|
|
|
## 1. Understand the Topic
|
|
|
|
**Topic to document:** $ARGUMENTS.topic
|
|
|
|
First, gather context about this topic:
|
|
- What is it and why does it matter?
|
|
- Who is the target audience?
|
|
- What should readers be able to do after reading?
|
|
|
|
## 2. Choose Document Type
|
|
|
|
Select the appropriate structure:
|
|
|
|
### Conceptual Documentation
|
|
For explaining what something is and how it works.
|
|
|
|
### Getting Started Guide
|
|
For helping users accomplish their first task.
|
|
|
|
### How-To Guide
|
|
For task-focused instructions with specific goals.
|
|
|
|
### Best Practices
|
|
For guidance on optimal usage patterns.
|
|
|
|
## 3. Apply Writing Standards
|
|
|
|
### Voice and Tone
|
|
- Write like you're helping a smart colleague who just joined
|
|
- Use "you" not "users"
|
|
- Use present tense
|
|
- Use active voice
|
|
- Be assertive but not arrogant
|
|
|
|
### Structure
|
|
- Sentence case for headings
|
|
- Short sentences (one idea each)
|
|
- Short paragraphs (2-3 sentences)
|
|
- Use `---` dividers between major sections
|
|
- Include examples
|
|
|
|
### Must Include
|
|
- Clear value statement at the start
|
|
- Key characteristics or steps
|
|
- Working examples
|
|
- Links to related content
|
|
- Next steps at the end
|
|
|
|
## 4. Dispatch Agent
|
|
|
|
For complex documentation, dispatch the functional-writer agent:
|
|
|
|
```
|
|
Task tool:
|
|
subagent_type: "ring-tw-team:functional-writer"
|
|
model: "opus"
|
|
prompt: "Write a [document type] for [topic]. Target audience: [audience].
|
|
The reader should be able to [goal] after reading."
|
|
```
|
|
|
|
## 5. Review Before Publishing
|
|
|
|
After writing, use the docs-reviewer agent:
|
|
|
|
```
|
|
Task tool:
|
|
subagent_type: "ring-tw-team:docs-reviewer"
|
|
model: "opus"
|
|
prompt: "Review this documentation for voice, tone, structure, and completeness:
|
|
[paste documentation]"
|
|
```
|
|
|
|
## Quick Reference
|
|
|
|
### Document Structures
|
|
|
|
**Conceptual:**
|
|
```
|
|
# Concept
|
|
Definition paragraph
|
|
## Key characteristics
|
|
## How it works
|
|
---
|
|
## Related concepts
|
|
```
|
|
|
|
**Getting Started:**
|
|
```
|
|
# Getting started with X
|
|
## Prerequisites
|
|
---
|
|
## Step 1
|
|
## Step 2
|
|
---
|
|
## Next steps
|
|
```
|
|
|
|
**How-To:**
|
|
```
|
|
# How to X
|
|
## Before you begin
|
|
## Steps
|
|
## Verification
|
|
```
|
|
|
|
**Best Practices:**
|
|
```
|
|
# Best practices for X
|
|
## Practice 1
|
|
- Mistake:
|
|
- Best practice:
|
|
## Summary
|
|
```
|
|
|
|
Now proceed with documenting: **$ARGUMENTS.topic**
|