authoring-user-guide

Author end-user product guides from upstream specs using Diataxis documentation modes.

1|1|Updated May 24, 2026
One-click install
npx skills add https://github.com/bm629/agent-skills --skill authoring-user-guide-bm629
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: authoring-user-guide
Source: https://github.com/bm629/agent-skills/tree/main/skills/authoring-user-guide
Command: npx skills add https://github.com/bm629/agent-skills --skill authoring-user-guide-bm629

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Writing end-user documentation from scratch often produces confusing guides that mix tutorials, how-tos, and reference material, invent product behaviors, or go stale after product changes. This Skill provides a structured method for authoring accurate, plain-language user guides derived strictly from upstream documents. ## Core Features & Use Cases - Diataxis-Keyed Authoring Method: Produces a getting-started tutorial, one task-oriented how-to per user goal, conceptual explanation, a complete feature/config reference, troubleshooting/FAQ, and a glossary — with the four documentation modes kept distinct. - Accuracy and Usability Bar: Enforces a 12-condition quality bar covering goal coverage, exact UI-label naming, plain language, accessibility, findability, and troubleshooting sourced from known error states. - Versioned Amend Workflow: Performs scoped staleness sweeps when the product changes, updating every stale reference across all modes and recording a revision-history entry. - Use Case: Given a feature-spec, user-flows, and wireframes for a SaaS product, produce a complete help-center guide where every step traces to actual product behavior and every control is named by its exact UI label. ## Quick Start Use authoring-user-guide to write an end-user guide for my product based on the attached feature-spec, user-flows, and wireframes.

Frequently Asked Questions about authoring-user-guide

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write an end-user guide from a feature spec?

Derive one task-oriented how-to per user goal found in the user-flows or feature-spec, write a single-path getting-started tutorial, and complete the reference over the whole product surface. Every step must trace to an upstream behavior; surface gaps as explicit assumptions rather than inventing steps.

What is the Diataxis framework for documentation?

Diataxis separates documentation into four modes: tutorials (one guaranteed learning path), how-to guides (imperative numbered steps), explanation (concepts with no steps), and reference (neutral, complete description). Mixing these modes is the most common cause of confusing documentation.

How do I update user documentation after a product change?

Run a scoped amend: identify the changed units, sweep every guide location referencing the changed or renamed capability across all modes, re-make internal coherence, and bump the doc version with a revision-history entry. Never silently patch only the sections you remember.

When should I not use this user guide authoring approach?

Do not use it for developer-tool adoption or integration narratives (use a developer-guide skill) or for HTTP/SDK endpoint catalogs (use an api-reference skill). It also does not review finished guides; a separate review-side gate asserts the same quality bar.

How do I make software documentation accessible and plain-language?

Define every term and acronym on first use, prefer short sentences and everyday words, name controls by their exact label rather than color or location, give links meaningful text, and nest headings in order. Judge readability by whether a non-technical reader can follow it, not by a score.