# Manual Guide

> Use when creating or updating an end-user manual or reference guide for an ERP or SaaS feature; use project-requirements for product scope and professional-word-output for final DOCX production.

- Skill: `peterbamuhigire/manual-guide` (Agent Skill)
- Install (CLI): `npx skillmds@latest add peterbamuhigire/manual-guide`
- Raw SKILL.md: https://api.skillmd.com/api/skills/peterbamuhigire/manual-guide/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: peterbamuhigire (https://skillmd.com/u/peterbamuhigire)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/peterbamuhigire/manual-guide

---


## Platform Notes

- Optional helper plugins may help in some environments, but they must not be treated as required for this skill.

# Manual Guide (End-User Documentation)
Acknowledgement: Shared by Peter Bamuhigire, techguypeter.com, +256 784 464178.

<!-- dual-compat-start -->
## Use When

- Generate end-user manuals and reference guides for ERP modules. Use when the user asks to document a feature, write a user manual, or sync a reference guide. This skill is explicitly separate from doc-architect (which manages AI guidance docs...
- The task needs reusable judgment, domain constraints, or a proven workflow rather than ad hoc advice.

## Do Not Use When

- The task is unrelated to `manual-guide` or would be better handled by a more specific companion skill.
- The request only needs a trivial answer and none of this skill's constraints or references materially help.


## Manual Guide Required Context
- Gather relevant project context, constraints, and the concrete problem to solve.
- Confirm the desired deliverable: design, code, review, migration plan, audit, or documentation.


## Manual Guide Core Method Notes
- Read this `SKILL.md` first, then load only the referenced deep-dive files that are necessary for the task.
- Apply the ordered guidance, checklists, and decision rules in this skill instead of cherry-picking isolated snippets.
- Produce the deliverable with assumptions, risks, and follow-up work made explicit when they matter.

## Quality Standards

- Keep outputs execution-oriented, concise, and aligned with the repository's baseline engineering standards.
- Preserve compatibility with existing project conventions unless the skill explicitly requires a stronger standard.
- Prefer deterministic, reviewable steps over vague advice or tool-specific magic.


## Manual Guide Existing Failure Notes
- Treating examples as copy-paste truth without checking fit, constraints, or failure modes.
- Loading every reference file by default instead of using progressive disclosure.


## Manual Guide Core Deliverables
- A concrete result that fits the task: implementation guidance, review findings, architecture decisions, templates, or generated artifacts.
- Clear assumptions, tradeoffs, or unresolved gaps when the task cannot be completed from available context alone.
- References used, companion skills, or follow-up actions when they materially improve execution.

## Evidence Produced

| Category | Artifact | Format | Example |
|----------|----------|--------|---------|
| Release evidence | End-user manual | Markdown doc covering feature walkthrough, screenshots, and FAQ per ERP module | `docs/manuals/inventory-manual.md` |

## References

- Use the links and companion skills already referenced in this file when deeper context is needed.
## Inputs

| Artefact | Source or provider | Requirement | If absent |
|---|---|---|---|
| Verified product behaviour, UI states, roles, and screenshots | product repository or product owner | required | Produce a missing-evidence checklist, not invented steps |

## Capability contract

Read access to product behaviour, role rules, and the current interface is required. Manual edits need explicit authority; screenshot capture, product mutation, and publication require their own approval.

## Degraded mode

Fallback without product access, screenshots, or render capability: return a qualified procedure outline, mark affected steps and page checks unassessed, and withhold invented instructions.

## Decision rules

| Choice | Action | Failure avoided |
|---|---|---|
| Observed behaviour conflicts with draft manual | Stop and verify the product | Publishing unsafe instructions |


## Outputs
| Artefact | Consumer | Observable acceptance condition |
|---|---|---|
| User manual source and verification record | end users and support team | Each procedure matches the product and covers errors, permissions, and recovery |


## Manual Guide Evidence Notes 1
- Record verified screens, roles, procedure test results, screenshot versions, error-path checks, and render gaps.

## Worked example

Document invoice creation as a numbered task, identify the required role, show the success state, and include recovery for validation failure.

<!-- dual-compat-end -->
Create **end-user manuals** and **reference guides**. This is **not** for AI instruction documents. Do **not** edit or generate AGENTS.md or other AI guidance files when this skill is used.

## Why Manuals Matter (SaaS Baseline)

End-user manuals and system guides are **required** deliverables for any SaaS application. Features are not considered complete until:

- A user-facing manual exists for the feature
- The manual includes step-by-step instructions, screenshots/visuals, and edge cases
- The manual is aligned with the feature spec and user workflows

**Documentation Standards (MANDATORY):** ALL manual files must follow strict formatting rules:
- **500-line hard limit** per manual page - no exceptions
- **Two-tier structure**: Manual index/TOC + Individual topic pages (max 500 lines each)
- **Smart subdirectory grouping** in `/manuals/` by module
- **See `doc-standards.md` for complete requirements**

## Trigger Phrases

Activate when the user asks to:

- "Document feature [X]"
- "Write manual for [Module]"
- "Sync reference guide"

## Contextual Discovery (Intelligence Phase)

Before writing a single word, analyze these four pillars:

1. **Plans**: Scan `docs/plans/**/*.md` to understand business intent and user stories.
2. **Schema**: Scan `database/schema/*.sql` to identify constraints, triggers, and auto-generated fields.
3. **Codebase**: Read implementation in `src/` or `app/` to see actual UI behavior and data flow.
4. **Documentation**: Check `docs/*` for style guides or technical debt notes.

## Output Structure (Dual-Workflow)

Every guide must include:

1. **Conceptual Overview**
   - Why the feature exists
   - How it works from a business perspective

2. **Procedural Steps**
   - Numbered steps for the happy path
   - Use bold for UI elements (**buttons**, **menus**, **fields**)

3. **Technical Reference**
   - Tables for auto-generated fields, required inputs, and background triggers

4. **Edge Cases**
   - Derived from schema constraints and validation rules

## Comprehensive Manual Standards (Required)

Use these standards to design manuals for SaaS web apps. Summarize and adapt per module.

### 1) Documentation Strategy

- Define audience personas (first-time users, regular users, admins, integrators)
- Define documentation types (getting started, feature guides, troubleshooting, API docs)
- Maintain a content audit checklist per release

### 2) Information Architecture

Organize manuals with a clear hierarchy:

- Getting Started
- Tutorials & Guides
- How-To Articles
- Reference (feature specs, error codes, shortcuts)
- Troubleshooting
- Best Practices
- What’s New

### 3) Writing & Microcopy Standards

- Use active voice and direct instructions
- Provide numbered, testable steps
- Use consistent UI terms and button labels
- Include FAQ and common errors

### 4) Visual & Media Standards

- High-resolution screenshots, annotated where needed
- Blur sensitive data
- Use consistent naming and alt text
- Optional short videos with captions

### 5) Accessibility & Localization

- Meet WCAG accessibility basics (contrast, headings, alt text, keyboard nav)
- Prepare for translation and locale formatting

### 6) Maintenance & Versioning

- Update manuals alongside feature releases
- Track changes via version control and changelogs
- Use analytics/feedback to prioritize improvements

### 7) Distribution & Promotion

- Provide in-app help links and searchable docs
- Publish release notes and guided walkthroughs
- Maintain downloadable print/PDF versions

## Tone & Style

- Professional, instructional, literal-minded
- Use tables to compare workflows (e.g., POS vs Direct Sales)
- Avoid implementation details that are irrelevant to end users

## Manual Delivery Requirements (Required)

- Manuals must be created in `/manuals/` using subdirectories for major areas.
- Create a core page: `/public/user-manuals.php` based on the standard template (e.g., `skeleton.php`).
- The core page should dynamically include manual files, e.g. `user-manuals.php?manual=pos-system`.
- When asked to design a manual:
  1.  Check if `/public/user-manuals.php` exists.
  2.  Check if `/manuals/` exists and contains subdirectories.
  3.  If no folders exist, study the codebase and create **up to 10** top-level manual sections.
  4.  Create `/manuals/AGENTS.md` describing the directory purpose and what each subfolder should contain.
  5.  Create the manual PHP file for the requested module in its subfolder.

## Manual UI Expectations (Web)

- Make manuals **enjoyable** and **interactive**, not static help pages.
- Use a clean, high-contrast layout with subtle depth (glassmorphism-like panels).
- Provide a top progress indicator and section anchors.
- Provide a fast live search/omnibox (Cmd/Ctrl+K) with visual previews when feasible.
- Use highlighted UI callouts (dim rest of page on hover/focus of a term).
- Ensure mobile readability and fast load time.

## Manual PDF Expectations

- Produce a clean, print-ready manual for export.
- Support a dark-mode style variant where feasible.
- Use high-quality typography (sans for headings, monospace for field names).
- Include visual anchors (clean UI illustrations rather than heavy screenshots).
- Optional QR code links for video walkthroughs or live demos.

## Tool Permissions

- Allowed: `read_file`, `list_dir`, `grep_search`, `file_search`, `create_file`, `apply_patch`
- Use edits only for manuals and `/public/user-manuals.php` scaffolding

## Output Formatting

- Manuals should be created as PHP files in `/manuals/<section>/` and included dynamically by `user-manuals.php`

## Cross-References to SDLC & Documentation Skills

### Related Skills

| Skill | Relationship |
|-------|-------------|
| `sdlc-user-deploy` | SDLC-standard user documentation (User Manual, Training Materials, Ops Guide). This skill produces **in-app PHP manuals**; `sdlc-user-deploy` produces **SDLC-standard markdown docs**. Use both for complete coverage. |
| `sdlc-planning` | SRS defines features that need manuals. Use SRS feature list as manual scope checklist. |
| `sdlc-design` | API docs and SDD inform technical reference sections in manuals. |
| `sdlc-testing` | Test cases reveal edge cases that should be documented in manuals. |
| `doc-architect` | Generates AI guidance docs (AGENTS.md). **NOT** end-user manuals — use this skill instead. |
| `feature-planning` | Specs include Documentation Impact notes that define manual requirements. |
| `spec-architect` | Specs are "manual-ready" — use their workflow descriptions for manual content. |
| `project-requirements` | User workflows and business rules inform manual content. |
| `report-print-pdf` | Report export patterns — reference in manual sections about report features. |

### When to Use Which Documentation Skill

| Need | Skill |
|------|-------|
| In-app PHP manual for ERP module | `manual-guide` (this skill) |
| SDLC-standard user manual (markdown) | `sdlc-user-deploy` |
| AI guidance docs (AGENTS.md) | `doc-architect` |
| Project README and CLAUDE.md updates | `update-claude-documentation` |
| Feature spec with documentation impact | `spec-architect` or `feature-planning` |

---

**Back to:** [Skills Repository](../../CLAUDE.md)
**Related:** route to the active SDLC documentation, architecture, or feature-planning skill through the repository router.
**Last Updated:** 2026-02-20


## Workflow
1. Identify audience, role, task, verified product behaviour, and delivery format.
2. Map procedures to real screens, permissions, success states, and failure recovery.
3. Stop when product behaviour or a required screenshot cannot be verified.
4. Draft and test procedures; recover by recording the missing evidence and withholding the affected instruction.


## Manual Guide Evidence Notes 2
| Evidence | Consumer | Acceptance |
|---|---|---|
| Procedure verification and render-QA record | Support team and release owner | Each procedure is checked against the product and its error path |


## Anti-Patterns
- Inventing a button or menu. Fix: verify the product state.
- Omitting role prerequisites. Fix: state permissions before each task.
- Documenting only the happy path. Fix: include errors and recovery.
- Using stale screenshots without warning. Fix: recapture or label the version gap.
- Publishing an untested procedure. Fix: execute or mark it not assessed.