write-user-docs

What this skill does

# 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

```markdown
# [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]

![Screenshot placeholder](screenshot-url)

> **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

```markdown
## [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**:
1. What this area is for
2. Why it's empty
3. 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**:
1. What happened (briefly)
2. 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**:
1. Confirm what was done
2. 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

```markdown
# 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"