User Guide Generator

Detailed Skill Workflow

1. Analyze the Request

When the user provides a feature, workflow, or requirement:

• Identify the target audience (end users, not developers)
• Extract functional requirements and steps
• Note any prerequisites or setup requirements
• Identify key actions and outcomes

2. Ask Clarification Questions (Only When Essential)

Only ask questions when critical information is missing:

• User roles/permissions: "Who can perform this action?" (if not clear)
• Prerequisites: "Are there any requirements before starting?" (if not mentioned)
• Expected outcome: "What should users expect to see/achieve?" (if unclear)
• Error scenarios: "What should users do if something goes wrong?" (if relevant)

Do NOT ask:

• Questions about technical implementation details
• Questions that can be inferred from context
• Redundant questions about information already provided

3. Create Execution Plan

Before generating the full guide, create a plan.md file in the target directory (temp/user_guide/<subject>/plan.md). This acts as a storyboard.

Structure for plan.md:

# Process Plan: [Subject]

## Flow Sequence
1. **Start Page**: [Route/URL]
2. **Action [1]**: Click [Button Name] -> Goes to [Next Page/Route]
3. **Action [2]**: Fill [Form Fields] -> Click [Submit Button]
4. **End Page**: [Final Route/Success State]

## UI Elements
- **Buttons**: [List buttons to interact with]
- **Routes**: [List distinct URLs involved]
- **Key Pages**: [List pages to screenshot]

4. Execute and Capture

• Tool Selection: Use MCP Playwright tools (user-Playwright) by default for better screenshot quality and reliability. Use cursor-ide-browser only if requested.
• Default Credentials: Use [email protected] / allsafe@2025 (from create_superuser command) unless specified otherwise.
• Follow the sequence in plan.md.
• Capture screenshots for each key page/step defined in the plan.
• Screenshot Storage:
  • When using Playwright MCP (user-Playwright): Screenshots are saved to .playwright-mcp/temp/user_guide/<subject>/. MOVE them immediately to temp/user_guide/<subject>/ after capture.
  • When using cursor-ide-browser: Screenshots may be saved to workspace root or a default location. MOVE them immediately to temp/user_guide/<subject>/ after capture.
  • Rename them clearly (e.g., main.png, step1_dashboard.png).
  • Important: Always verify screenshots are in temp/user_guide/<subject>/ before finalizing the guide.

5. Generate the User Guide

IMPORTANT: The guide will be imported into a structured format with:

• Guide Item (main guide with title, description, and main image)
• Guide Steps (individual steps with title, description, and optional step images)

Structure your markdown guide as follows:

# Guide Title

Brief overview description that explains what this guide covers and who should use it.

## Step 1: [Action/Title]

Detailed instructions for this step.
- What to do
- What to expect
- Important notes

![Step 1 Screenshot](step1.png)

## Step 2: [Action/Title]

Detailed instructions for this step.
...

## Step 3: [Action/Title]

...

Markdown Structure Rules

1. H1 (# Title): Becomes the guide title
2. Content after H1 (before first H2): Becomes the guide description (overview, prerequisites, who should use it)
3. H2 (## Step Title): Each H2 becomes a separate step with its title
4. Content under H2: Becomes the step description
5. Images in steps: Reference images as ![Alt](stepX.png) - these will be attached to that step

Content Guidelines

• Keep the description (between H1 and first H2) concise - this is the overview
• Include prerequisites, permissions, and overview information in the description
• Each step should be self-contained with clear instructions
• Use descriptive step titles that indicate the action (e.g., "Navigate to Dashboard", "Fill Out Employee Form")
• Include screenshots in relevant steps to guide users visually

6. Writing Guidelines

Language and Tone

• Clear and objective: Use simple, direct language
• Non-technical: Avoid jargon, technical terms, or code references
• User-focused: Write from the user's perspective ("You can...", "Your data...")
• Action-oriented: Use imperative mood for instructions ("Click the button", not "The button should be clicked")
• Numbered References: Use (Step X) or [X] to refer to specific actions in the flow.

Structure

• Use headings and subheadings for organization
• Use bullet points for lists
• Use numbered lists for sequential steps
• Use bold for important terms or UI elements
• Use code blocks only for user input examples (e.g., email addresses, file names)

Content Rules

• Do NOT invent functionality: Only document what was explicitly provided
• Do NOT assume technical details: If not provided, omit or ask
• Do NOT include code: This is for end users, not developers
• Be specific: Use actual UI element names, button labels, menu items as provided
• Include context: Explain why steps are needed, not just what to do

7. Output Format and Storage

1. Create Directory:

   • Create: temp/user_guide/<subject>/ (where <subject> is a kebab-case name like employee-onboarding)

2. Generate Content:

   • Save the markdown guide as temp/user_guide/<subject>/guide.md (or any .md filename)
   • Main Image (optional): main.png or main.jpg → Attached to the guide item
   • Step Images (optional): step1.png, step2.png, etc. → Attached to respective steps

3. Image Naming Best Practices:

   temp/user_guide/employee-onboarding/
   ├── guide.md
   ├── main.png              # Guide cover image
   ├── step1_login.png       # Step 1 image (descriptive name)
   ├── step2_profile.png     # Step 2 image
   ├── step3_upload.png      # Step 3 image
   └── step4_submit.png      # Step 4 image
   

4. Image References in Markdown:

   • Use relative paths: ![Login Screen](step1_login.png)
   • First image reference in each step content will be attached to that step
   • Images should be referenced in the step where they're most relevant

8. Finalize and Prepare for Import

After generating the guide and screenshots:

1. Verify File Structure:

   temp/user_guide/<subject>/
   ├── guide.md (or any .md file)
   ├── main.png (main guide image - optional)
   ├── step1.png (step screenshots - optional)
   ├── step2.png
   └── ...
   

2. Review Content with User:

   • Show the guide markdown content
   • Confirm screenshots are in the correct location
   • Get user approval for content and structure

3. Provide Import Instructions and Confirmation:

After approval, provide these step-by-step instructions to the user:

# Step 1: Navigate to backend directory
cd backend

# Step 2: Run the import command
python manage.py import_user_guide <subject> --category "Category Name"

# Example:
python manage.py import_user_guide employee-onboarding --category "HR"

Command Parameters:

• <subject>: The folder name in temp/user_guide/ (e.g., employee-onboarding)
• --category: Category name to organize the guide (created if doesn't exist)
  • Common categories: "HR", "Finance", "Operations", "System", "Documentation"

What the import command does:

1. Creates/updates the guide category
2. Creates/updates the guide item with title and description
3. Attaches main.png as the guide's main image (if present)
4. Creates steps from each H2 section in the markdown
5. Attaches step images to their respective steps (if referenced in markdown)

Post-Import:

• Guide will be visible at: https://allsafeportal.com.au/userguide
• Users can navigate: Categories → Select Category → View Guide → See Steps

4. Request Confirmation and Execute:

After providing the import instructions, ask the user for confirmation:

"Would you like me to run the import command now? (Yes/No)"

• If the user answers Yes: Execute the command automatically
• If the user answers No: Do not run the command, just provide the instructions
• Wait for explicit confirmation before executing

9. Delegation to Subagent (Optional)

If the guide is complex or requires specialized writing:

• Consider delegating to the user-guide-writer subagent
• Provide the subagent with the functional context
• The subagent will handle the detailed writing

Example Usage

User Request

Create a user guide for the employee onboarding feature.
Users need to: 1) Log in, 2) Complete profile, 3) Upload documents, 4) Submit for review.
Only managers can approve submissions.

Skill Application

1. Create directory: temp/user_guide/employee-onboarding/

2. Generate plan.md (execution plan)

3. Capture screenshots:

   • main.png - Dashboard/starting page
   • step1.png - Login screen
   • step2.png - Profile form
   • step3.png - Document upload interface
   • step4.png - Submission confirmation

4. Generate guide.md:

   # Employee Onboarding
   
   This guide walks you through the employee onboarding process. New employees should complete these steps within their first week. Only managers can approve submissions.
   
   **Prerequisites**: You must have login credentials provided by HR.
   
   ## Step 1: Log In to the System
   
   1. Navigate to https://allsafeportal.com.au
   2. Enter your email and password
   3. Click "Sign In"
   
   ![Login Screen](step1.png)
   
   ## Step 2: Complete Your Profile
   
   1. Click on "My Profile" in the navigation menu
   2. Fill in required fields: Name, Phone, Address
   3. Click "Save Changes"
   
   ![Profile Form](step2.png)
   
   ## Step 3: Upload Required Documents
   
   1. Navigate to "Documents" section
   2. Click "Upload Document"
   3. Select document type and choose file
   4. Click "Upload"
   
   ![Document Upload](step3.png)
   
   ## Step 4: Submit for Review
   
   1. Review all information for accuracy
   2. Click "Submit for Manager Review"
   3. Wait for manager approval notification
   
   ![Submission Confirmation](step4.png)
   

5. Provide import command and request confirmation:

   cd backend
   python manage.py import_user_guide employee-onboarding --category "HR"
   

   Then ask: "Would you like me to run the import command now? (Yes/No)"

   • If Yes: Execute the command
   • If No: Do not execute

Checklist

Before finalizing the guide:

• Structure:
  • H1 title is clear and descriptive
  • Description (before first H2) includes overview and prerequisites
  • Each step is an H2 section with clear title
  • Steps are in correct sequential order
• Content:
  • All provided information is included
  • No invented functionality
  • Language is clear and non-technical
  • Steps are actionable with clear instructions
  • Prerequisites and permissions are stated in description
  • Important warnings/notes are included
• Images:
  • All screenshots are in temp/user_guide/<subject>/ directory
  • main.png exists (optional but recommended)
  • Step images are referenced in correct step sections
  • Image references use relative paths
• File Organization:
  • Directory temp/user_guide/<subject>/ exists
  • Markdown file (.md) is present
  • All referenced images exist in the directory
• Import Ready:
  • Import command is documented for user
  • Category name is specified
  • Subject (folder name) matches directory name

Common Patterns

Feature Guides

• Focus on what users can do, not how it's built
• Include visual references (screenshot placeholders)
• Show before/after states when relevant

Workflow Guides

• Map the complete flow from start to finish
• Include decision points and branches
• Show error handling and recovery steps

Process Guides

• Break complex processes into manageable steps
• Include checkpoints or verification steps
• Provide completion criteria

Troubleshooting Common Issues

Import Command Fails

Issue: Directory not found for subject "xyz"

• Solution: Verify the directory exists at temp/user_guide/<subject>/
• Check the subject name matches the folder name exactly (case-sensitive)

Issue: No markdown file found in directory

• Solution: Ensure there's at least one .md file in the directory
• File can be named anything as long as it has .md extension

Steps Not Created

Issue: Import succeeds but no steps appear

• Solution: Ensure your markdown has H2 sections (##)
• Verify H2 sections have content below them
• Check that steps aren't nested under H3 or deeper headings

Images Not Attached

Issue: Images don't appear in the guide

• Solution:
  • For main image: Ensure file is named exactly main.png, main.jpg, or main.jpeg
  • For step images: Ensure images are referenced in markdown with ![Alt](filename.png)
  • Verify all image files exist in temp/user_guide/<subject>/ directory
  • Check file paths are relative, not absolute

Description Missing

Issue: Guide has no description

• Solution: Add content between H1 and the first H2 section
• This content becomes the guide's description/overview

File Organization Example

temp/user_guide/employee-onboarding/
├── guide.md                    ✓ Main guide file (required)
├── main.png                    ✓ Guide cover image (optional)
├── step1_login.png            ✓ Step images (optional)
├── step2_profile.png
├── step3_documents.png
└── plan.md                     ✓ Execution plan (optional, not imported)

Import Command:

cd backend
python manage.py import_user_guide employee-onboarding --category "HR"

Result:

• Guide title: Extracted from H1 in guide.md
• Guide description: Content between H1 and first H2
• Guide image: main.png attached
• Steps: Each H2 becomes a step with its content and image (if referenced)