User Flows in Documentation — Complete Guide

User flows map the paths users take through documentation to complete tasks. Learn how to design flows for common user journeys and identify friction points.

What You'll Learn

You will learn how to create user flow diagrams, identify common user journeys, and design documentation to support task completion.

Why It Matters

Users come to documentation to complete tasks. Understanding their flow helps you place the right content at each step.

Real-World Use

DodaTech maps user flows for common tasks like "Setting up the API" and "Debugging an error." Each flow links the relevant tutorials, references, and troubleshooting guides.

flowchart LR
  A[User Flow] --> B[Entry Point]
  A --> C[Steps]
  A --> D[Decision Points]
  A --> E[Exit]
  B --> F[Search]
  B --> G[Navigation]
  C --> H[Tutorial]
  C --> I[Reference]
  D --> J[Success]
  D --> K[Error]
  J --> L[Next Task]
  K --> M[Troubleshooting]
  F:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Mapping User Flows

Common Documentation Flows

Flow Diagram Example

flowchart LR
  A[User searches 'authentication'] --> B{Found?}
  B -->|Yes| C[Read Getting Started]
  B -->|No| D[Search 'API auth']
  C --> E[Follow Setup Steps]
  E --> F{Works?}
  F -->|Yes| G[Build Feature]
  F -->|No| H[Read Troubleshooting]
  H --> E

Designing Flows

Step 1: Identify Key Tasks

def identify_key_tasks(support_tickets, analytics):
    tasks = []
    # From support tickets: what do users struggle with?
    for ticket in support_tickets:
        if ticket['type'] == 'setup':
            tasks.append({
                'name': f"Set up {ticket['feature']}",
                'priority': ticket['frequency'],
            })
    # From analytics: what do users search for?
    for query in analytics['top_queries']:
        tasks.append({
            'name': f"Find {query}",
            'priority': query['volume'],
        })
    return sorted(tasks, key=lambda x: -x['priority'])[:5]

tickets = [{'type': 'setup', 'feature': 'API', 'frequency': 200}]
analytics = {'top_queries': [{'query': 'authentication', 'volume': 500}]}
tasks = identify_key_tasks(tickets, analytics)
for t in tasks:
    print(f"{t['name']} (priority: {t['priority']})")

Expected output:

Find authentication (priority: 500)
Set up API (priority: 200)

Step 2: Map Content to Each Step

Step 3: Link the Content

# user-flow.yaml
flow: "Set up API authentication"
steps:
  - step: Install SDK
    content: "/python/installation/"
    next: "/python/authentication-setup/"
  
  - step: Configure credentials
    content: "/python/authentication-setup/"
    next: "/python/making-first-request/"
  
  - step: Make first request
    content: "/python/making-first-request/"
    next: null
    related:
      - "/python/error-handling/"
      - "/python/api-reference/"

Analyzing Flows

Friction Points

def find_friction_points(analytics_data):
    friction = []
    for page in analytics_data['pages']:
        if page['bounce_rate'] > 70:
            friction.append({
                'page': page['path'],
                'issue': 'High bounce rate - users not finding what they need',
            })
        if page['exit_rate'] > 50:
            friction.append({
                'page': page['path'],
                'issue': 'High exit rate - users leaving without continuing',
            })
    return friction

data = {'pages': [
    {'path': '/python/setup/', 'bounce_rate': 75, 'exit_rate': 60},
    {'path': '/python/usage/', 'bounce_rate': 30, 'exit_rate': 20},
]}
for f in find_friction_points(data):
    print(f"{f['page']}: {f['issue']}")

Expected output:

/python/setup/: High bounce rate - users not finding what they need
/python/setup/: High exit rate - users leaving without continuing

Common Mistakes

1. Assuming Linear Flows

Users do not always start at the beginning. Design flows that can be entered at any step.

2. No Decision Points

Real users make choices. Include branches for success and failure paths.

3. Ignoring Error Recovery

When something goes wrong, users need troubleshooting content. Map the error recovery path.

4. Content Gaps in Flows

If step 3 requires content that does not exist, the flow breaks. Complete the content before documenting the flow.

5. Static Flows

User behavior changes as your product evolves. Review and update flows regularly.

Practice Questions

1. What is a user flow in documentation?

A map of the steps users take through documentation to complete a task.

2. How do support tickets help identify user flows?

Tickets reveal what users struggle with, which maps to the steps in their flow.

3. What is a friction point in a user flow?

A step where users get stuck, leave, or fail to complete the task.

4. Why should flows include error recovery paths?

Users make mistakes. Error recovery paths guide them back to the main flow.

5. Challenge: Map a user flow for a common documentation task. Include the entry point, 5 steps, decision points, and error recovery paths.

FAQ

Mini Project

Map user flows for 3 common documentation tasks. For each flow, identify entry points, steps, decision points, required content, and error recovery paths.

What's Next

Now that you understand user flows, learn IA Patterns for common design solutions. Then complete the IA Project.