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

User guide writing modes and boundaries

Use this reference to keep user-guide-writing narrow and reliable inside the documentation cluster.

Canonical scope

user-guide-writing owns customer-facing or admin-facing guidance that helps someone complete a workflow in the product.

Typical outputs:

• getting-started guides
• tutorials
• task-based how-to articles
• FAQs
• help-center updates after shipped UI/workflow changes

Route-outs

Route to technical-writing

Use technical-writing when the real job is for builders/operators:

• design docs
• architecture docs
• ADRs
• runbooks
• migration plans
• internal developer guides

Question to ask: Is the reader mainly building, operating, or changing the system rather than using the product?

Route to api-documentation

Use api-documentation when the output is for developers integrating with an API/SDK:

• OpenAPI / Swagger reference
• endpoint docs
• authentication examples
• SDK method docs
• developer portal content

Question to ask: Is the reader calling the product through code rather than clicking through the UI?

Route to changelog-maintenance

Use changelog-maintenance when the work is primarily release communication:

• CHANGELOG.md upkeep
• semantic version summaries
• release-note formatting
• "what changed" publishing

Question to ask: Is the task mainly summarizing shipped change history rather than teaching a task?

Diátaxis-style mode split

• Getting started: shortest path to first success
• Tutorial: learn by doing with context and milestones
• How-to: solve a specific task fast
• FAQ: answer repeated questions and route deeper
• Release-help update: patch existing user docs after a shipped UI or workflow change

If one draft tries to do all of these, split it.

High-signal boundary examples

• "Write docs for setting up SSO in the admin console" → user-guide-writing
• "Write the SSO architecture and rollout plan" → technical-writing
• "Document the SSO REST endpoints and webhook schema" → api-documentation
• "Summarize SSO changes in v2.4.0 release notes" → changelog-maintenance

Common failure modes

• turning a help article into a product-tour brochure
• burying prerequisites after the first step
• mixing support FAQ, migration warnings, and tutorial context into one giant page
• copying internal implementation details that the end user cannot act on
• forgetting to note plan/role/version differences that change the UI path

Maintenance signals for user-guide-writing

The hardest part of user-facing docs is not initial drafting. It is knowing when a guide is stale and what to update first.

Strong update signals

• UI labels, menus, or screen order changed after a release
• support starts re-answering the same question manually
• help-center search terms reveal zero-result or poor-result queries
• a feature gained new permissions, role checks, or plan limits
• screenshots no longer match the current UI
• users reach the page but still fail the task
• related docs disagree about the same workflow

Weak but useful signals

• article has high traffic but low helpfulness votes
• launch notes mention a feature change but the help article stays untouched
• internal SMEs warn that the existing instructions are now "close enough" instead of correct
• a tutorial requires too much hidden context from onboarding calls or support macros

Practical maintenance loop

1. Detect the stale signal. 2. Confirm the product truth: new UI path, permissions, expected result. 3. Decide the smallest doc mode that solves the problem. 4. Patch the live guide before writing a broad new manual. 5. List companion docs that must stay in sync. 6. Record screenshots/placeholders that need replacement.

Common sync surfaces

• help-center article ↔ tutorial
• getting-started guide ↔ FAQ
• release update ↔ existing task-based article
• public guide ↔ support macro / saved reply

Good maintenance outputs

• concise stale-doc refresh plan
• updated how-to article with new steps
• FAQ patch that answers the new blocker
• release-help update that explains what changed and links the affected guides

Boundary reminder

Maintenance work still belongs in user-guide-writing only when the output is customer-facing guidance. If the real work is release-note summarization, use changelog-maintenance; if the work is internal rollout or migration coordination, use technical-writing.

User Guide Writing Mode Structures

Use these as default section skeletons after user-guide-writing chooses the primary mode.

Getting-started guide

# Get Started with <Product / Feature>

## Who this is for
## What you will accomplish
## Prerequisites
## Step 1: <first action>
## Step 2: <next action>
## Step 3: <first success state>
## Common mistakes
## Next steps
## Where to get help

Tutorial

# Tutorial: <Outcome>

## What you will learn
## Time and prerequisites
## Before you start
## Step 1
## Step 2
## Step 3
## Check your result
## Why it matters
## Related guides / next steps

How-to guide

# How to <Task>

## Before you begin
## Step 1
## Step 2
## Step 3
## Verify success
## Troubleshooting
## Related tasks

FAQ

# Frequently Asked Questions

## <Category>
### <Question>
Short answer
Longer answer if needed
Link to the deeper guide if one exists

Release-help update / refresh packet

# <Feature / Workflow> help update

## What changed
## Who is affected
## Updated steps or UI callouts
## Screenshot refreshes needed
## Related guides to patch
## Assumptions to verify

Output-shape reminders

• Prefer a single-page artifact when the user only needs one guide.
• Use guide plus FAQ when the same blockers recur but the main task is still one page.
• Use a refresh packet when existing docs are stale after a release and the task is primarily patching, not rewriting.
• Use a guide set only when one page cannot honestly serve the onboarding, task, and follow-up jobs without becoming a blob.

Workflow checklist for user-facing docs

Use this checklist before drafting or revising a guide.

1. Audience and task

• Who is the reader? End user, admin, manager, or mixed?
• What exact task are they trying to complete?
• Is this first-time onboarding or a repeat task?
• What would success look like from the user's point of view?

2. Preconditions

Collect the assumptions that most often break a guide:

• account role / permissions
• plan / edition limits
• required setup already completed
• browser / app / device constraints
• data or files the user needs beforehand

3. Source-of-truth inputs

Before drafting, gather the smallest credible evidence set:

• current UI labels and navigation
• working step order
• expected success state
• likely error or blocker states
• existing support replies / recurring questions
• release changes that made the old doc stale

4. Structural choice

Choose only one primary doc shape:

• getting started
• tutorial
• how-to
• FAQ
• release-help update

If the content needs more than one, split it into multiple pages.

5. Writing rules

• Put the user goal near the top.
• Keep steps observable and action-oriented.
• Mention warnings before the risky step.
• Prefer exact UI text when it reduces confusion.
• Use short paragraphs and bullets.
• Give the user a success check.

6. Screenshot discipline

Screenshots are useful when:

• the transition is visually confusing
• a menu or setting is easy to miss
• the user needs to confirm they are in the right place

Avoid screenshots when:

• the same point is obvious from the text
• the UI changes often and the image will rot quickly
• the image does not add new information

Track:

• screenshot needed
• screenshot to refresh
• screenshot intentionally omitted

7. Maintenance notes

Add or update:

• related guides that need syncing
• release/version note if the flow recently changed
• owner/reviewer if the doc is launch-critical
• assumptions still awaiting verification

8. Final ship check

• Can a new reader complete the task without private context?
• Are prerequisites and blockers visible early?
• Is the guide scoped to one main outcome?
• Are route-outs to adjacent docs types clear?
• Would support or success teams be comfortable linking this doc directly?