Writing User Guides in X402

By X402 Team | Last Updated: February 2026

Direct Answer

User guides in X402 are task-focused markdown documents organized by user journey or feature, written in plain language with screenshots, step-by-step instructions, and contextual help to enable non-technical users to accomplish their goals independently.

Overview

User guides are the bridge between your product and your users. Unlike technical documentation or API references, user guides are written for end users who want to accomplish tasks, not understand how the system works. Great user guides reduce support tickets, improve user satisfaction, and drive product adoption.

User Guides vs Other Content Types

User Guide (End-User Focus)

Audience: Non-technical users Goal: Help users accomplish tasks Example: "How to Create a Report"
  • Task-oriented
  • Plain language
  • Screenshots and visuals
  • Assumes no technical knowledge

Tutorial (Learning Focus)

Audience: New users learning Goal: Teach through hands-on practice Example: "Your First Project: Build a Dashboard"
  • Learning path
  • Step-by-step with exercises
  • Builds confidence
  • Progressive complexity

API Documentation (Developer Focus)

Audience: Software developers Goal: Enable integration Example: "POST /api/reports Reference"
  • Technical and precise
  • Code samples
  • Parameter specifications
  • Assumes programming knowledge

Administrator Guide (System Admin Focus)

Audience: System administrators Goal: Configure and maintain system Example: "Configure SSO Authentication"
  • Infrastructure focus
  • Security considerations
  • Command-line operations
  • Assumes IT knowledge

Why X402 for User Guides?

Version Control

  • Track updates alongside product releases
  • Branch for different product versions
  • Review changes via pull requests
  • Historical record of all documentation

Batch Organization

  • Group by user journey or workflow
  • Feature-based organization
  • Role-based guides (admin, editor, viewer)
  • Progressive disclosure from basic to advanced

Multi-Format Publishing

  • Markdown to HTML for web
  • Generate PDF for offline use
  • Convert to in-app help
  • Create printable quick reference

Collaboration

  • Writers can review each other's work
  • Subject matter experts contribute
  • Localization teams translate
  • All changes tracked and attributed

User Guide Structure in X402

Recommended Organization

Option 1: By User Journey

batch-guides-getting-started/
├── INDEX.md
├── create-account.md
├── set-up-profile.md
├── invite-team-members.md
└── first-project.md


batch-guides-reports/
├── INDEX.md
├── create-report.md
├── customize-report.md
├── schedule-report.md
└── share-report.md



batch-guides-administration/
├── INDEX.md
├── manage-users.md
├── set-permissions.md
├── configure-integrations.md
└── billing-invoices.md

Option 2: By Feature

batch-guides-projects/
batch-guides-tasks/
batch-guides-reports/
batch-guides-integrations/
batch-guides-settings/

Option 3: By User Role

batch-guides-admin/
batch-guides-editor/
batch-guides-viewer/

User Guide Template

# [Task or Feature Name]


Direct Answer

[One sentence explaining what this guide helps users do]


Overview



What You'll Learn:

    

  • Key point 1
    • 

  • Key point 2
    • 

  • Key point 3
    • 




Time Required: [Estimate]



Prerequisites:

    

  • Prerequisite 1
    • 

  • Prerequisite 2
    • 




Before You Begin



[Any important context or setup needed]



Permissions Required: [Role or permission level]



Steps



Step 1: [Action Verb + What]



[Brief explanation of what we're doing in this step]



    

  1. [Specific instruction with location]
    2. 

  2. [Specific instruction with what to do]
    3. 

  3. [Specific instruction with expected result]
    4. 




Screenshot: [Image showing this step]



Tip: [Helpful tip or best practice]



⚠️ Warning: [Common mistake to avoid]



Step 2: [Action Verb + What]



[Continue pattern...]



Verify It Worked



[How to confirm the task was successful]



You should now see:

    

  • [ ] Expected result 1
    • 

  • [ ] Expected result 2
    • 

  • [ ] Expected result 3
    • 




What's Next?



Now that you've completed this task, you might want to:

    

  • [Next logical step]
    • 

  • [Related task]
    • 

  • [Advanced option]
    • 




Troubleshooting



Issue: [Common Problem]



Symptoms:

    

  • What the user sees
    • 

  • Error messages
    • 




Solution:

    

  1. Step to resolve
    2. 

  2. Step to resolve
    3. 




Still having trouble? [Link to support]



FAQ



Q: [Common question]
A: [Clear answer]



Q: [Common question]
A: [Clear answer]



Related Guides





Need Help?

Practical Example: Complete User Guide

Here's a real user guide following best practices:

# Create Your First Report


Direct Answer



Create custom reports in minutes by selecting your data source, choosing metrics, applying filters, and customizing the visualization to track your business KPIs.



Overview



Reports help you visualize and analyze your data. You can create reports to track sales, monitor user activity, analyze trends, and share insights with your team.



What You'll Learn:

    

  • How to select a data source for your report
    • 

  • How to choose and configure metrics
    • 

  • How to apply filters to focus on specific data
    • 

  • How to customize report visualizations
    • 

  • How to save and share your report
    • 




Time Required: 10 minutes



Prerequisites:

    

  • You have an active account
    • 

  • You have access to at least one data source
    • 

  • Your role has "Create Reports" permission
    • 




Before You Begin



Reports pull data from connected data sources like databases, spreadsheets, or third-party apps. Make sure your data source is connected before creating a report.



Permissions Required: Editor or Admin role



Data Requirements: At least one connected data source with data



Steps



Step 1: Start a New Report



Navigate to the Reports section and create a new report.



    

  1. Click Reports in the left navigation menu
    2. 

  2. Click the + New Report button in the top right
    3. 

  3. Select Blank Report from the template options
    4. 



New Report Button


Tip: You can also start from a template for common report types like Sales Dashboard or User Analytics.



Step 2: Choose Your Data Source



Select where you want to pull data from.



    

  1. In the Data Source panel on the right, click Select Data Source
    2. 

  2. Choose your data source from the list (e.g., "Sales Database")
    3. 

  3. Click Connect
    4. 



Select Data Source


You'll see a preview of available tables and fields below the data source name.



Available Data Sources:

    

  • Databases (PostgreSQL, MySQL, MongoDB)
    • 

  • Spreadsheets (Google Sheets, Excel)
    • 

  • Third-party apps (Salesforce, HubSpot, Stripe)
    • 




⚠️ Warning: If you don't see your data source listed, ask your administrator to connect it first.



Step 3: Select Metrics



Choose what data you want to display in your report.



    

  1. Click + Add Metric in the metrics section
    2. 

  2. Choose a field from your data source (e.g., "Revenue")
    3. 

  3. Select an aggregation method:
    4. 



    

  • Sum: Total of all values
    • 

  • Average: Mean value
    • 

  • Count: Number of records
    • 

  • Min/Max: Lowest or highest value
    • 




    

  1. Name your metric (e.g., "Total Revenue")
    2. 

  2. Click Add
    3. 



Add Metric


Example Metrics:

    

  • Total Revenue (Sum of Revenue)
    • 

  • Average Order Value (Average of Order Amount)
    • 

  • Customer Count (Count of Customer ID)
    • 

  • Highest Sale (Max of Revenue)
    • 




Tip: You can add multiple metrics to compare different data points on the same report.



Step 4: Apply Filters (Optional)



Narrow down your data to focus on specific information.



    

  1. Click + Add Filter in the filters section
    2. 

  2. Choose a field to filter by (e.g., "Date")
    3. 

  3. Select filter type:
    4. 



    

  • Equals: Exact match
    • 

  • Contains: Partial match
    • 

  • Greater than / Less than: Numeric comparison
    • 

  • Between: Date or number range
    • 

  • In list: Multiple values
    • 




    

  1. Enter your filter criteria (e.g., "Last 30 Days")
    2. 

  2. Click Apply
    3. 



Apply Filter


Common Filters:

    

  • Date range (Last 7 days, This month, Custom range)
    • 

  • Status (Active, Completed, Pending)
    • 

  • Region (North America, Europe, Asia)
    • 

  • Category (Product type, Customer segment)
    • 




Tip: You can combine multiple filters to drill down into specific data subsets.



Step 5: Customize Visualization



Choose how you want to display your data.



    

  1. Click the Visualization tab
    2. 

  2. Select a chart type:
    3. 



    

  • Bar Chart: Compare categories
    • 

  • Line Chart: Show trends over time
    • 

  • Pie Chart: Show proportions
    • 

  • Table: Display detailed data
    • 

  • Number: Show single metric
    • 




    

  1. Configure chart options:
    2. 



    

  • Colors: Choose color scheme
    • 

  • Labels: Show/hide data labels
    • 

  • Legend: Position and visibility
    • 

  • Axes: Customize axis labels and scales
    • 




    

  1. Preview your changes in real-time
    2. 



Customize Visualization


Choosing the Right Chart:

    

  • Trends over time? Use line chart
    • 

  • Comparing categories? Use bar chart
    • 

  • Showing parts of a whole? Use pie chart
    • 

  • Need exact numbers? Use table
    • 

  • Single KPI? Use number widget
    • 




Step 6: Save Your Report



Save your report so you can access it later.



    

  1. Click Save in the top right corner
    2. 

  2. Enter a report name (e.g., "Monthly Revenue Report")
    3. 

  3. Add a description (optional but recommended)
    4. 

  4. Choose a folder location
    5. 

  5. Click Save Report
    6. 



Save Report


Naming Best Practices:

    

  • Use descriptive names: "Q1 Sales by Region" not "Report 1"
    • 

  • Include time period if relevant: "2024 User Growth"
    • 

  • Add purpose: "Executive Dashboard" or "Team Weekly Review"
    • 




Step 7: Share Your Report (Optional)



Share your report with team members or make it public.



    

  1. Click the Share button
    2. 

  2. Choose sharing option:
    3. 



    

  • Specific people: Enter email addresses
    • 

  • Anyone with link: Copy shareable link
    • 

  • Public: Publish to web (if enabled)
    • 




    

  1. Set permissions:
    2. 



    

  • View only: Recipients can view but not edit
    • 

  • Can edit: Recipients can modify the report
    • 




    

  1. Add a message (optional)
    2. 

  2. Click Send
    3. 



Share Report


Tip: Use "View only" for stakeholders and "Can edit" for team members who need to maintain the report.



Verify It Worked



Your report should now be created and accessible. Confirm:



    

  • [ ] You can see your report in the Reports list
    • 

  • [ ] The report displays the correct metrics
    • 

  • [ ] Filters are working as expected
    • 

  • [ ] Visualization shows your data clearly
    • 

  • [ ] Report is saved with the correct name
    • 

  • [ ] Shared recipients received access (if you shared)
    • 




Quick Check: Navigate to Reports → My Reports and find your report by name.



What's Next?



Now that you've created your first report, explore these features:





Advanced Options:

    

  • Add calculated fields for custom metrics
    • 

  • Create drill-down reports for detailed analysis
    • 

  • Use report templates to speed up creation
    • 

  • Build interactive reports with dynamic filters
    • 




Troubleshooting



Issue: "No Data Available" Message



Symptoms:

    

  • Report shows "No data available" or empty visualization
    • 

  • Metrics show 0 or null values
    • 




Solution:

    

  1. Check your filters - they might be too restrictive
    2. 

  2. Verify your data source has data for the selected time period
    3. 

  3. Confirm you have permission to view the data source
    4. 

  4. Try selecting a different date range
    5. 




Still having trouble? Contact Support



Issue: Chart Not Displaying Correctly



Symptoms:

    

  • Chart appears blank or distorted
    • 

  • Data labels overlap or are unreadable
    • 

  • Colors don't match selections
    • 




Solution:

    

  1. Try switching to a different visualization type
    2. 

  2. Reduce the number of data points shown
    3. 

  3. Clear your browser cache and refresh
    4. 

  4. Check if browser zoom is set to 100%
    5. 




Issue: Can't Save Report



Symptoms:

    

  • Save button is grayed out
    • 

  • Error message when clicking Save
    • 

  • Changes aren't persisting
    • 




Solution:

    

  1. Verify you have "Create Reports" permission
    2. 

  2. Check that you've given the report a name
    3. 

  3. Ensure you've selected at least one metric
    4. 

  4. Try refreshing the page and recreating
    5. 




Issue: Report Takes Too Long to Load



Symptoms:

    

  • Report loading spinner shows for >30 seconds
    • 

  • Browser becomes unresponsive
    • 

  • Timeout errors
    • 




Solution:

    

  1. Reduce the date range to load less data
    2. 

  2. Remove unnecessary metrics or filters
    3. 

  3. Use aggregated data instead of row-level data
    4. 

  4. Contact admin about database performance
    5. 




FAQ



Q: How many metrics can I add to one report?
A: You can add up to 10 metrics per report. For more complex analysis, consider creating multiple reports or a dashboard.



Q: Can I edit a report after sharing it?
A: Yes! Any changes you make will be visible to everyone who has access to the report. The report updates in real-time.



Q: How often does report data refresh?
A: Reports refresh automatically every time you open them. Data freshness depends on your data source sync schedule (typically every 15 minutes to 24 hours).



Q: Can I embed reports in other applications?
A: Yes, if you have the Professional or Enterprise plan. Go to Share → Embed and copy the iframe code.



Q: What's the difference between a report and a dashboard?
A: A report shows one visualization or data view. A dashboard combines multiple reports in a single view for comprehensive insights.



Q: Can I duplicate an existing report?
A: Yes! Find the report in your Reports list, click the three-dot menu, and select "Duplicate." This is helpful for creating variations of the same report.



Q: How do I delete a report I no longer need?
A: Open the report, click the three-dot menu in the top right, select "Delete," and confirm. Deleted reports can be recovered from trash for 30 days.



Tips & Best Practices



Naming Conventions


    

  • Use consistent naming: "[Department] [Metric] [Time Period]"
    • 

  • Example: "Sales Revenue Q1 2024"
    • 

  • Include purpose: "Weekly Team Review" or "Executive Summary"
    • 




Report Organization


    

  • Create folders for different teams or categories
    • 

  • Use tags to make reports searchable
    • 

  • Archive old reports instead of deleting them
    • 




Performance Optimization


    

  • Use appropriate date ranges (don't load years of data if you need only days)
    • 

  • Apply filters early to reduce data volume
    • 

  • Consider using scheduled reports for large datasets
    • 




Data Accuracy


    

  • Verify your metrics are correctly aggregated
    • 

  • Test filters to ensure they capture the right data
    • 

  • Cross-check totals with source system
    • 

  • Add descriptions explaining metric calculations
    • 




Sharing Wisely


    

  • Only share with people who need access
    • 

  • Use "View only" by default
    • 

  • Document who has access and why
    • 

  • Review sharing permissions quarterly
    • 




Related Guides



Getting Started:




Reports:




Advanced:




Video Tutorial



Prefer to watch? Check out our 5-minute video tutorial:



📺 Watch: Create Your First Report



Need Help?



Self-Service:




Contact Us:




Enterprise Customers:

    

  • Contact your dedicated account manager
    • 

  • Submit a ticket in the priority queue

Best Practices for User Guides

1. Write for Your Audience

Know who you're writing for:

  • Beginners: Assume no prior knowledge, explain everything
  • Power users: Focus on efficiency and advanced features
  • Administrators: Include technical details and configuration

❌ "Configure the SMTP relay parameters" ✅ "Set up email sending by entering your email provider's settings"

2. Use Active Voice and Action Verbs

Start every step with an action verb:

  • ✅ "Click the Save button"
  • ✅ "Enter your email address"
  • ✅ "Select a data source from the dropdown"

❌ "The Save button should be clicked" ❌ "Your email address can be entered"

3. One Action Per Step

Keep steps focused and simple:

❌ Bad: "Click Settings, then navigate to Users, click Add User, enter their email and name, select their role, and click Send Invite"

✅ Good:

  1. Click Settings in the navigation menu
  2. Click Users in the sidebar
  3. Click Add User
  4. Enter the user's email and name
  5. Select their role from the dropdown
  6. Click Send Invite

4. Include Screenshots Strategically

Add screenshots for:

  • Complex interfaces
  • First-time tasks
  • Visual elements users need to find
  • Confirmation of success

Screenshot Best Practices:

  • Annotate with arrows, boxes, or numbers
  • Use consistent styling (same theme, same zoom level)
  • Keep UI clean (hide personal data)
  • Update screenshots when UI changes
  • Include alt text for accessibility

5. Anticipate Questions

Add these sections:

  • Tips: Helpful suggestions
  • Warnings: Common mistakes
  • FAQ: Questions you've heard before
  • Troubleshooting: Common problems and solutions

6. Link Liberally

Create a web of help content:

  • Link to related guides
  • Link to prerequisite setup
  • Link to next logical steps
  • Link to detailed reference docs

7. Test Your Instructions

Before publishing:

  • [ ] Follow your own steps from scratch
  • [ ] Have someone unfamiliar test them
  • [ ] Verify screenshots match current UI
  • [ ] Check all links work
  • [ ] Confirm prerequisites are accurate

8. Keep It Current

User guides require maintenance:

  • Update when UI changes
  • Revise when features change
  • Archive outdated guides
  • Add "Last updated" date

9. Provide Multiple Learning Paths

Different users prefer different formats:

  • Written step-by-step guides
  • Video tutorials
  • Interactive demos
  • Quick reference cards
  • In-app tooltips

10. Make It Scannable

Users skim, they don't read:

  • Use descriptive headings
  • Break up long paragraphs
  • Add bulleted lists
  • Highlight key information
  • Use bold for UI elements

User Guide Quality Checklist

Before publishing a user guide:

Content

  • [ ] Clear Direct Answer section
  • [ ] States what the user will accomplish
  • [ ] Lists prerequisites explicitly
  • [ ] Provides realistic time estimate
  • [ ] Steps are numbered sequentially
  • [ ] Each step has ONE action
  • [ ] All UI elements bolded (buttons, menus)
  • [ ] Includes verification section
  • [ ] Provides "What's Next" guidance

Visual Elements

  • [ ] Screenshots for complex steps
  • [ ] Screenshots are annotated
  • [ ] Screenshots show current UI
  • [ ] Diagrams for complex flows
  • [ ] Alt text for all images

Help & Support

  • [ ] Troubleshooting section included
  • [ ] FAQ addresses common questions
  • [ ] Links to related guides
  • [ ] Contact support information
  • [ ] Warnings for common mistakes

Quality

  • [ ] Tested by following steps exactly
  • [ ] Reviewed by subject matter expert
  • [ ] Checked by editor for clarity
  • [ ] Verified all links work
  • [ ] Appropriate reading level (6th-8th grade)

Accessibility

  • [ ] Alt text for images
  • [ ] Headings in logical hierarchy
  • [ ] Links have descriptive text (not "click here")
  • [ ] Color not used as only indicator
  • [ ] Works with screen readers

Organizing User Guides in X402

INDEX.md Structure

# User Guides


Quick Start



New to [Product]? Start here:

    

  1. Create Your Account
    2. 

  2. Set Up Your Profile
    3. 

  3. Invite Your Team
    4. 

  4. Create Your First Project
    5. 




Guides by Feature



Projects




Reports




Administration




Guides by Role



Administrators:




Editors:




Viewers:




Video Tutorials





Need Help?

Writing for Different Skill Levels

Beginner Guides

  • Explain every term
  • Assume no prior knowledge
  • Include lots of screenshots
  • Provide encouragement
  • Link to learning resources

Example: "A dashboard is a page that shows multiple reports together, like a control panel for your data."

Intermediate Guides

  • Assume basic familiarity
  • Focus on specific tasks
  • Fewer screenshots
  • Link to beginner guides for basics

Example: "Add widgets to your dashboard by clicking the + icon. See Create Your First Dashboard if you haven't built one yet."

Advanced Guides

  • Assume expert knowledge
  • Focus on efficiency and optimization
  • Include technical details
  • Provide shortcuts and tips

Example: "Use keyboard shortcut Cmd+K to open the command palette and type 'widget' for quick dashboard editing."

Related Questions

How long should a user guide be? As long as needed to complete the task, typically 500-2000 words (5-15 steps). If longer, consider breaking into multiple guides.

Should we include videos in user guides? Yes! Embed or link to videos as an alternative learning path. Some users prefer written steps, others prefer watching.

How do we keep guides updated when UI changes? Tag guides with version numbers, use automated screenshot tools, and review quarterly. Consider dynamic screenshots that update automatically.

What reading level should we target? Aim for 6th-8th grade reading level for general audiences. Use tools like Hemingway App to check readability.

How do we handle guides for multiple product versions? Use Git branches for each version or include version selectors in your documentation site. Clearly mark which version each guide applies to.

Quality Standards

  • [x] Follows AEO format with Direct Answer
  • [x] Includes comprehensive template
  • [x] Contains realistic complete example
  • [x] Documents best practices
  • [x] Provides quality checklist
  • [x] Shows organization strategies
  • [x] Includes multiple skill level approaches
  • [x] Ready for production

Start Building with X402

Get our free X402 Implementation Starter Kit with ready-to-use templates, code examples, and best practices.

What is included:

  • Quick-start implementation templates
  • API integration examples
  • Configuration best practices guide

Get the Free Starter Kit