6.4 KiB
6.4 KiB
description, disable-model-invocation
| description | disable-model-invocation |
|---|---|
| Write user-facing documentation for features and products | false |
Write User Docs
Create clear, helpful documentation for end users.
When to Use
- When launching a new feature
- When users are asking support questions
- When creating help center content
- When writing in-app guidance
Used By
- Customer Support (primary owner)
- Content Creator (writing)
- Product Manager (requirements)
- UI/UX Designer (in-app copy)
Documentation Types
1. Help Article
Full documentation for a feature or workflow
2. FAQ Entry
Quick answer to common questions
3. In-App Guidance
Tooltips, empty states, onboarding text
4. Troubleshooting Guide
Steps to resolve common issues
Help Article Template
# [Action-Oriented Title]
Brief intro paragraph explaining what this article covers and who it's for.
---
## Before You Start
What users need before following this guide:
- [Prerequisite 1]
- [Prerequisite 2]
- [Account type or permission required]
---
## [Main Task]
### Step 1: [Clear action]
[Explanation of what to do]
> **Tip**: [Helpful tip for this step]
### Step 2: [Clear action]
[Explanation of what to do]
### Step 3: [Clear action]
[Explanation of what to do]
---
## [Secondary Task] (if applicable)
Steps for related functionality...
---
## Troubleshooting
### [Common Issue 1]
**Problem**: [What the user experiences]
**Solution**:
1. [Step to resolve]
2. [Step to resolve]
### [Common Issue 2]
**Problem**: [What the user experiences]
**Solution**: [How to fix it]
---
## Frequently Asked Questions
**Q: [Common question]?**
A: [Clear answer]
**Q: [Common question]?**
A: [Clear answer]
---
## Related Articles
- [Related Article 1](link)
- [Related Article 2](link)
---
## Need Help?
If you're still having trouble, [contact support](link) and we'll help you out.
FAQ Template
## [Question in user's words?]
[Direct answer to the question - lead with the answer, not background]
### More Details
[Additional context if needed]
### Related
- [Link to full article if exists]
- [Related FAQ]
In-App Copy Guidelines
Empty States
Structure:
- What this area is for
- Why it's empty
- How to fill it
Example:
No projects yet
Create your first project to start tracking your work.
[Create Project]
Tooltips
Rules:
- Keep under 100 characters
- Explain the action, not the obvious
- Include "why" when helpful
Good:
Export your data as CSV for analysis in other tools
Bad:
Click to export
Error Messages
Structure:
- What happened (briefly)
- What to do next
Example:
Couldn't save changes
Check your internet connection and try again.
[Retry]
Anti-patterns:
❌ Error 500
❌ Failed to save
❌ Invalid input
❌ Something went wrong
Confirmation Messages
Structure:
- Confirm what was done
- Next action (optional)
Example:
Project created successfully
[View Project] or [Create Another]
Loading States
Keep it simple:
Loading...
Saving...
Processing...
Or be specific:
Uploading file... 45%
Generating report...
Connecting to [Service]...
Writing Principles
1. Use Plain Language
Do:
- "Click the Save button"
- "Your changes are saved"
- "Enter your email address"
Don't:
- "Execute the save operation"
- "Modifications have been persisted"
- "Input your electronic mail identifier"
2. Lead with the Action
Do:
- "To create a project, click the + button"
- "Export your data from Settings > Export"
Don't:
- "The + button, which is located in the top right corner of the interface, can be used to create a new project"
3. Use Second Person ("You")
Do:
- "Your account"
- "You can export..."
- "Your changes are saved"
Don't:
- "The user's account"
- "Users can export..."
- "The changes are saved"
4. Be Specific, Not Vague
Do:
- "Enter a password with at least 8 characters"
- "This file is 2.4 MB (maximum: 5 MB)"
Don't:
- "Enter a secure password"
- "File size must be acceptable"
5. Explain Why (When Helpful)
Do:
- "Archive this project to free up your dashboard while keeping all data"
- "Set up 2-factor authentication to protect your account"
Don't:
- Over-explain obvious actions
Troubleshooting Guide Template
# Troubleshooting: [Problem Category]
## Quick Fixes
Try these first:
1. [ ] Refresh the page
2. [ ] Clear browser cache
3. [ ] Try a different browser
4. [ ] Check internet connection
---
## [Specific Problem 1]
### Symptoms
- [What user sees or experiences]
- [Related error messages]
### Cause
[Brief explanation of why this happens]
### Solution
**Option A**: [First solution]
1. [Step 1]
2. [Step 2]
**Option B**: [If Option A doesn't work]
1. [Step 1]
2. [Step 2]
### Prevention
[How to avoid this in the future]
---
## [Specific Problem 2]
[Same structure as above]
---
## Still Having Issues?
If none of the above solutions work:
1. **Collect information**:
- Browser and version
- Screenshots of the issue
- Steps to reproduce
2. **Contact support**:
- [Support link]
- Include the information above
---
## Related Articles
- [Related troubleshooting guide]
- [Feature documentation]
Documentation Checklist
Before Publishing
- Title is action-oriented
- Language is plain and clear
- Steps are numbered and specific
- Screenshots are included (if helpful)
- Prerequisites are listed
- Troubleshooting included
- Related articles linked
- Tested by someone unfamiliar with feature
Content Quality
- Answers the user's question
- Scannable (headers, bullets, short paragraphs)
- Accurate and up-to-date
- Consistent with product UI text
- Accessible (alt text, clear structure)
After Publishing
- Update when product changes
- Review support tickets for gaps
- Track page views and search terms
- Update based on user feedback
Voice and Tone Guide
Be Helpful
Guide users to success, don't just document features.
Be Clear
Use simple words, short sentences, direct instructions.
Be Friendly
Conversational but professional. Not robotic, not too casual.
Be Confident
"Click Save" not "You might want to click Save"
Be Respectful
Don't blame users for errors. "Something went wrong" not "You did something wrong"