user-guide-writing（用户指南写作）

User Guide Writing

Use this skill when the deliverable is customer-facing or admin-facing documentation that helps someone complete a workflow in the product.

user-guide-writing is the documentation-cluster anchor for:

• getting-started / first-success guides
• tutorials and guided walkthroughs
• task-based how-to articles
• FAQs and support-oriented answer sets
• release-facing help updates after shipped UI/workflow changes
• small guide sets that combine one primary page with the minimum supporting companion docs

Read these support docs before choosing the mode or boundary:

• references/document-modes-and-boundaries.md
• references/mode-structures.md
• references/workflow-checklist.md
• references/maintenance-signals.md

When to use this skill

• A product needs a getting-started guide that gets a new user to the first successful outcome.
• A feature launch needs a tutorial or how-to article for real product users.
• A help center needs a task-based article, FAQ, or troubleshooting-friendly walkthrough.
• Support pain keeps recurring and the answer should become durable customer-facing documentation.
• A workflow changed and the existing user-facing steps, screenshots, warnings, or prerequisites need to be updated.
• A request really needs one guide plus a tiny companion packet instead of a huge mixed-purpose document.

When not to use this skill

• The main job is an internal spec, architecture doc, ADR, runbook, migration plan, or builder-facing implementation guide → use technical-writing.
• The main job is API reference, SDK docs, webhook docs, developer quickstarts, or developer-portal content → use api-documentation.
• The main job is release notes, CHANGELOG.md, migration announcements, or shipped-change summaries → use changelog-maintenance.
• The main job is a deck, launch presentation, workshop slide set, or visual review artifact → use presentation-builder.
• The main job is product positioning, marketing messaging, lifecycle email copy, or launch copy → use marketing-automation.
• The main job is building in-app onboarding mechanics or product-tour UX → use the relevant product/UX skill first, then use this skill for the durable written companion docs.

Instructions

Step 1: Classify one primary mode

Normalize the request before drafting.

user_guide_mode:
  primary_mode: getting-started | tutorial | how-to | faq | release-help-update
  audience: end-user | admin | manager | mixed | unknown
  experience_level: first-time | familiar | advanced | mixed | unknown
  docs_surface: help-center | docs-site | in-app-companion | pdf | unknown
  source_of_truth: product-ui | release-notes | support-tickets | sme-notes | mixed | unknown
  maintenance_need: one-off | recurring | stale-doc-rewrite | launch-critical
  output_shape: single-page | guide-plus-faq | refresh-packet | guide-set | unknown

Use one primary mode per run:

• getting-started → shortest path to first success
• tutorial → guided learning with context and milestones
• how-to → one practical task completed quickly
• faq → concise repeated questions plus route-outs to deeper guides
• release-help-update → patch user-facing docs after shipped UI or workflow change

Step 2: Confirm audience, task, and route-outs

Answer these before writing:

1. Who will follow the doc, and what role or permissions do they have?
2. What exact task or outcome should they achieve?
3. Which prerequisites, plan limits, or environment assumptions could break the flow?
4. Which neighboring skills must stay out of scope?

Quick route-out table:

Step 3: Gather the minimum user-facing evidence

Do not draft from vibes alone. Pull the smallest credible evidence set first:

• current UI labels, navigation, and states
• prerequisites, permissions, and plan / edition assumptions
• expected result after each important step
• likely blockers, empty states, and branching conditions
• screenshots or screenshot placeholders only where they reduce confusion
• support questions, search terms, or recurring failure signals if available
• release changes that made the current guide stale

If details are incomplete, label assumptions explicitly instead of pretending the guide is verified.

Step 4: Choose the smallest fitting structure

Use references/mode-structures.md and keep only the sections the chosen mode needs.

Rules:

• If the request is one user outcome, prefer a single page.
• If the task needs one main guide plus recurring blockers, use guide plus FAQ.
• If the real work is patching stale pages after a release, use a refresh packet instead of rewriting a whole manual.
• If one draft starts doing onboarding, daily usage, troubleshooting, and release notes all at once, split it into a small guide set.

Step 5: Emit the smallest useful artifact packet

Default output shapes:

• single-page → one getting-started guide, tutorial, how-to, or FAQ page
• guide-plus-faq → one main guide plus a short FAQ or troubleshooting appendix
• refresh-packet → changed steps, stale screenshot list, affected companion docs, and assumptions to verify
• guide-set → a bounded set such as getting-started + FAQ or tutorial + how-to follow-up

Do not ship a broad handbook when the request only needs one page and a short sync list.

Step 6: Apply user-doc writing rules

• Lead with the task and audience, not implementation details.
• Name prerequisites early: role, permissions, plan limits, data required, browser/app/version assumptions.
• Prefer observable actions: what the user clicks, types, sees, and receives.
• Keep one major outcome per page.
• Call out branching conditions like role-specific UI or alternate paths.
• Give the user a success check so they know the task worked.
• Keep troubleshooting near the task instead of burying it in a generic appendix.
• Use screenshots intentionally at confusing transitions, not after every click.
• Link outward deliberately: FAQ → full guide, release-help update → affected articles, getting-started → next task.

Step 7: Run the maintenance and sync check

Use references/workflow-checklist.md and references/maintenance-signals.md before finalizing.

Verify:

1. The page type matches the user job.
2. Prerequisites and blockers appear before risky steps.
3. Screenshot placeholders are justified and trackable.
4. Related guides, FAQs, release updates, or support macros that must stay in sync are named.
5. Route-outs to technical-writing, api-documentation, and changelog-maintenance remain explicit when the request drifts.

Step 8: Return a brief or the finished artifact

Preferred brief shape before full drafting:

# User Guide Writing Brief

## Mode
- Primary mode:
- Why it fits:
- Audience:
- Output shape:

## Source material used
- Product truth / UI evidence:
- Support or release signals:
- Assumptions / gaps:

## Planned artifact packet
1. main page
2. companion FAQ / refresh list / sync note

## Writing notes
- Key user outcome:
- Known blockers / branching conditions:
- Route-outs kept out of scope:

If the user already asked for the finished artifact, produce the selected page or packet directly with the matching structure.

Examples

Example 1: First-success onboarding

Input

Write a getting-started guide for new workspace admins inviting their team and creating the first project.

Good output direction

• mode: getting-started
• output shape: single-page
• include prerequisites, step order, success check, and next steps
• keep internal implementation notes out of scope

Example 2: Release-driven doc refresh

Input

Update our help-center article for exporting reports because the Export button moved into the Reports header and only admins can choose XLSX now.

Good output direction

• mode: release-help-update
• output shape: refresh-packet
• call out changed UI, role differences, screenshot refreshes, and affected companion docs
• keep release-note summarization out of scope

Example 3: Support-to-FAQ conversion

Input

Turn these repeated billing support replies into a short FAQ for workspace owners.

Good output direction

• mode: faq
• output shape: single-page or guide-plus-faq
• keep answers short and link to the deeper task guide where needed
• surface role / plan caveats early

Example 4: Boundary with developer docs

Input

Refresh our public webhook quickstart and auth troubleshooting page for external developers.

Good output direction

• route to api-documentation
• explain that the main job is published developer-facing API docs, not end-user product guidance

Best practices

1. Choose the page type before writing the body.
2. Prefer one user outcome per page and one primary mode per run.
3. Use the smallest useful packet instead of a giant all-in-one guide.
4. Put prerequisites, permissions, and blockers before the user gets stuck.
5. Keep screenshots intentional and easy to refresh.
6. Use support/search/release signals to decide what to patch next.
7. Route internal docs, API docs, and release notes out instead of stretching the skill boundary.
8. Split mixed-purpose drafts into a guide set when the page starts teaching too many jobs.

References

• Diátaxis
• Google developer documentation style guide
• Microsoft Writing Style Guide
• GitLab documentation workflow
• Write the Docs — Docs as Code