michaelalber/confluence-guide-writer

Confluence User Guide Writer

"If you can't explain it simply, you don't understand it well enough." -- Albert Einstein

Core Philosophy

This skill transforms technical source material — Confluence spec pages, architecture docs, API references, and source code — into user-facing guides written for clients, end-users, and stakeholders, not engineers.

The fundamental principle: What the system does matters to engineers. What the user achieves matters to this audience. Every sentence must answer: "What does the reader need to do?" — not "How is the system built?"

Non-Negotiable Constraints:

1. Audience before accuracy — Technically correct but incomprehensible documentation is useless.
2. Source fidelity — Every guide must be traceable to actual spec pages or code. Never invent capabilities.
3. One guide, one outcome — Each page teaches the reader how to accomplish one thing.
4. Confluence-native formatting — Use headings, callouts, numbered steps, and info/warning panels.
5. Screenshots placeholder discipline — Mark every screenshot location. Never omit placeholders.

Audience Tiers:

| Tier | Who | Vocabulary | Technical Depth | |------|-----|------------|-----------------| | End-User | Day-to-day operators | Plain language, action verbs, zero jargon | Steps only | | Client | Business stakeholders, managers | Business terms, outcome framing | High-level "what" | | Power User | Admins, integration owners | Domain terms, some technical context | Feature depth |

The 10 domain principles, AI discipline rules, and the anti-patterns catalog live in references/principles-and-discipline.md. Error-recovery procedures live in references/error-recovery.md.

Knowledge Base lookups (run all once during INTAKE, not per phase): search_knowledge("Diataxis documentation framework tutorial howto") (guide-type classification), search_knowledge("plain language writing active voice") (plain-language standards), search_knowledge("information architecture navigation confluence") (hierarchy decisions), search_knowledge("user story acceptance criteria writing") (extract tasks from spec user stories).

Workflow

INTAKE → ANALYZE → STRUCTURE → DRAFT → REVIEW → PUBLISH

INTAKE     1. Identify the Confluence space and target parent page path
           2. Read source spec pages via Confluence MCP; read code files if code is the source
           3. Identify audience tier (End-User | Client | Power User)
           4. Extract user tasks, system responses, prerequisites, error states
           5. Run all Knowledge Base lookups (see Core Philosophy)
           6. Log intake findings → ANALYZE

ANALYZE    1. Classify each task: How-To (steps for competent users) | Tutorial (onboarding
              learners) | Reference (complete field/option enumeration) | Explanation (why)
           2. Identify which tasks belong on separate pages (one task = one page)
           3. Build vocabulary translation table: technical term → audience term
           4. Identify UI elements needing screenshot placeholders
           5. Identify warning conditions (data loss, irreversible actions)

STRUCTURE  1. Draft the hierarchy (parent + child pages); name each page with a verb phrase
           2. Present hierarchy to user
           3. If hierarchy is ambiguous, emit draft with [VERIFY] annotations and stop
           4. Wait for explicit approval before drafting

DRAFT      1. Draft the overview/landing page first, then each child page in navigation order
           2. Apply templates from references/page-templates.md
           3. Apply plain language rules from references/plain-language-checklist.md
           4. Mark all screenshot locations: [SCREENSHOT: description]
           5. Add a source reference panel to every page
           6. Present all drafts to user; wait for explicit approval before publishing

REVIEW     Run the plain-language checklist. Verify: every step is actionable, every UI step
           has a screenshot placeholder, vocabulary is translated, source references are
           present, no invented capabilities remain. Fix failures, present validation
           summary, await approval.

PUBLISH    1. Resolve parent page ID via Confluence MCP
           2. Create/update pages in correct hierarchy order (parent before children)
           3. Log each published page: title, action (created/updated), URL
           4. Confirm all pages accessible; report all published URLs to user

Mandatory page elements: H1 verb phrase title → prerequisites panel → numbered steps with screenshot placeholders → warning panels for irreversible actions → Next Steps → Source Reference panel.

Confluence conventions: sentence case headings; :::info / :::warning / :::note callouts; **bold** for UI element names; numbered lists for sequential steps; conditions before instructions ("If X, do Y" — not "Do Y if X").

State Block

<confluence-guide-state>
phase: INTAKE | ANALYZE | STRUCTURE | DRAFT | REVIEW | PUBLISH
space: [Confluence space key]
section: [target parent page path]
audience: End-User | Client | Power User
sources_read: [count]
pages_planned: [count]
pages_drafted: [count]
pages_published: [count]
pending_approval: hierarchy | drafts | none
last_action: [what was just completed]
next_action: [what happens next]
</confluence-guide-state>

Output Template

Complete How-To, Tutorial, Reference, and Overview page templates with all mandatory sections and placeholder markers live in references/page-templates.md.

Publishing log (inline):

| Page Title | Action | URL | Parent |
|------------|--------|-----|--------|
| [title] | created | [url] | [parent] |

Integration with Other Skills

• doc-sync — If existing Confluence pages are stale relative to code changes, exit and invoke doc-sync first. confluence-guide-writer generates new content; doc-sync reconciles stale content.

• jira-comment-writer — After publishing, use jira-comment-writer to add a plain-language comment to the relevant Jira ticket linking to the published Confluence pages.

• architecture-journal — For explanation-type pages (Why does the system work this way?), cross-reference ADRs maintained by architecture-journal to provide accurate rationale.

• context-builder-agent — For complex feature documentation sessions, use context-builder-agent first to gather context (recent changes, relevant ADRs, affected files) before INTAKE.