documentation-effective-user-documentation

name	documentation-effective-user-documentation
description	Imported TRAE skill from documentation/Effective_User_Documentation.md Use when this capability is needed.
metadata	{"author":"Ditto190"}

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 — distributed by TomeVault.