# Write User Docs > Write user-facing documentation for features and products - Skill: `yebot/write-user-docs` (Agent Skill) - Install (CLI): `npx skillmds@latest add yebot/write-user-docs` - Raw SKILL.md: https://api.skillmd.com/api/skills/yebot/write-user-docs/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: yebot (https://skillmd.com/u/yebot) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/yebot/write-user-docs --- # 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"