Persona Docs

Create user-centered documentation that defines who a product is for and how they interact with it. Persona docs establish the foundation for product-driven development — every feature decision, design choice, and prioritization call flows from understanding your users.

Installation

OpenClaw / Moltbot / Clawbot

npx clawhub@latest install persona-docs

When to Create

Persona docs should be the first thing fleshed out for any product. Even minimal documentation about who uses the product helps direct development and design decisions.

• •Project inception — before writing code, define who you're building for
• •Pivoting to a new audience — document the shift so the team aligns
• •Team lacks clarity on target users — when people disagree on "who is this for?"
• •Before major feature planning — validate that planned features serve actual users
• •New team member onboarding — give them context on who they're building for

Process

1. •Analyze the codebase — look for existing documentation, README, landing pages, or marketing copy that hints at the target audience
2. •Ask clarifying questions if the target user isn't clear:
   • •"Who is the primary user of this product?"
   • •"What problem does this solve for them?"
   • •"How would they discover this product?"
   • •"What's the first thing they'd do after finding it?"
3. •Start minimal — a few sentences per section is better than nothing
4. •Read the template — see references/template.md for the full structure
5. •Iterate — revisit and expand as you learn more about actual users

Core Components

1. Target User Profile

Who they are, their background, their context. Be specific enough to be useful.

Good: "Backend engineers at mid-size SaaS companies who debug production issues under time pressure, typically 3-8 years of experience, comfortable with command-line tools."

Too vague: "Developers."

Include:

• •Role, job title, or archetype
• •Technical level and relevant skills
• •Industry or domain context
• •When and where they'd use this product
• •Team size and organizational context

2. User Needs and Pain Points

The problems this product solves. What frustrations or gaps exist in their current workflow?

Structure as:

• •Primary pain point — the single biggest problem you solve
• •Secondary pain points — additional problems you address
• •Current workarounds — what they do today without your product
• •Why existing solutions fail — what alternatives exist and why they're insufficient

3. Discovery Path

How they find the product. This informs marketing, positioning, and first-impression design.

• •Search — what queries lead them here?
• •Referral — word of mouth, colleague recommendation?
• •Content — blog posts, tutorials, conference talks?
• •Marketplace — app store, plugin directory, package registry?
• •The hook — what makes them click "sign up" or "download"?

4. Onboarding Flow

The simplest possible path from "I found this" to "I'm getting value."

Define:

• •First encounter — landing page, app store listing, GitHub README
• •Registration/Login — minimum viable auth (email-only? OAuth? no account?)
• •Time to value — how quickly can they experience the core benefit?
• •First success moment — the specific action that makes them think "this is useful"
• •Friction points — where do users drop off, and how do you minimize that?

Example flow:

User lands on homepage → clicks "Try it" → pastes their data → sees result in <30 seconds → decides to create account

5. User Journey Map

Key touchpoints and interactions across the user lifecycle.

New User (Day 1):

• •Discovers product via [channel]
• •Takes [first action]
• •Achieves [first success]

Returning User (Week 1):

• •Key repeated action they perform
• •Features they explore
• •Integrations or customizations they set up

Power User (Month 1+):

• •Advanced features they rely on
• •Workflows they've established
• •How they'd describe the product to others

6. Feature Touchpoints

Map where users encounter key features in their journey:

Multi-Persona Products

If your product serves multiple distinct user types:

1. •Identify the primary persona first — who must you serve to survive?
2. •Document secondary personas separately — one file per persona
3. •Note conflicts — where persona needs clash, document the tradeoff
4. •Prioritize ruthlessly — you can't optimize for everyone simultaneously

Output Location

Place persona docs at:

• •docs/PERSONA.md — single file for simple products
• •docs/personas/ — directory for multiple personas

Keep it in the repo so it evolves with the product.

Quality Criteria

A good persona doc should:

• •Be specific enough that two team members would build the same feature from it
• •Include evidence — data, quotes, or observations, not just assumptions
• •Be actionable — reading it should change how you build
• •Be maintained — outdated personas are worse than none
• •Be honest — don't describe aspirational users; describe actual users

NEVER Do

1. •NEVER skip personas for a new product — building without knowing your user is guessing, and guessing is expensive
2. •NEVER describe users as demographics alone — "25-34 male" tells you nothing about what they need; describe behaviors and goals
3. •NEVER create personas in isolation — involve the team; one person's assumptions become the whole product's blind spots
4. •NEVER treat personas as permanent — users change, markets shift; review personas quarterly
5. •NEVER create more than 3 personas initially — if you try to serve everyone, you serve no one; start with your primary user
6. •NEVER write aspirational personas — document who actually uses your product, not who you wish did