# Documentation Effective User Documentation > Imported TRAE skill from documentation/Effective_User_Documentation.md Use when this capability is needed. - Skill: `tomevault-io/documentation-effective-user-documentation` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/documentation-effective-user-documentation` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/documentation-effective-user-documentation/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/documentation-effective-user-documentation --- # Skill: Writing Effective User Documentation ## Purpose To create guides, tutorials, and help articles that empower non-technical users to successfully use a product, reduce support tickets, and improve overall user satisfaction. ## When to Use - When launching a new product or major consumer-facing feature - When users frequently ask the same questions to support - To improve user onboarding and self-service capabilities ## Procedure ### 1. Know Your Audience Before writing, identify who you are writing for. - **Novice**: Needs step-by-step instructions and basic terminology. - **Intermediate**: Needs specific task-oriented guides. - **Expert**: Needs advanced tips, shortcuts, and troubleshooting. ### 2. The Structure of a Good Help Article 1. **Clear, Action-Oriented Title**: (e.g., "How to Reset Your Password", NOT "Password Recovery"). 2. **The "Why"**: A brief sentence explaining what the user will achieve. 3. **Numbered Steps**: Use numbered lists for sequential actions. 4. **Visual Aids**: Use annotated screenshots, GIFs, or short videos for complex steps. 5. **Notes & Warnings**: Use callouts for important information. 6. **Related Articles**: Link to other relevant guides. ### 3. Writing Style - **Use Active Voice**: (e.g., "Click the Save button", NOT "The Save button should be clicked"). - **Be Direct**: Avoid fluff. Start with the most important information. - **Use Consistent Terminology**: If you call it a "Dashboard", don't call it a "Home Screen" in the next paragraph. - **Chunk Information**: Use subheaders to break up long articles into scannable sections. ### 4. The 3-Step Review Process 1. **Technical Review**: Does the feature actually work this way? 2. **Editorial Review**: Is it free of typos and consistent with the brand voice? 3. **Usability Review**: Can a user actually follow these steps to complete the task? (Ideally, have someone who didn't build the feature test it). ## Best Practices - **Searchable Content**: Use keywords that users actually type into search engines (e.g., "forgot password", "reset login"). - **Keep it Updated**: Outdated documentation is worse than no documentation. Set a regular review schedule. - **Provide "Paths"**: Create "Getting Started" paths for new users rather than just a library of disconnected articles. - **Accessibility**: Ensure your documentation site is accessible (proper alt text on images, high contrast, keyboard navigable). - **Feedback Loop**: Allow users to rate articles ("Was this helpful?") to identify content that needs improvement. --- > Source: [Ditto190/crispy-nextjs-turborepo-monorepo](https://github.com/Ditto190/crispy-nextjs-turborepo-monorepo) — distributed by [TomeVault](https://tomevault.io).