Audience Analysis¶

Every documentation decision depends on understanding your audience. Who are they? What do they already know? What are they trying to accomplish? Without answers to these questions, you are guessing—and guesses create documentation that serves no one well.

Audience analysis is the systematic process of identifying and understanding your users. It informs vocabulary choices, content depth, structure, and format. Master this skill, and your documentation becomes genuinely useful rather than merely accurate.

Why Audience Analysis Matters¶

Documentation serves users. Without understanding users, you cannot serve them effectively.

Consider the same information for different audiences:

For a developer integrating an API:

POST requests to /api/v2/users require a JSON body with email (string, required) and role (enum: admin, user, viewer). Returns 201 on success with the created user object.

For a business analyst configuring the system:

To add a new user, go to Settings > User Management and click "Add User." Enter their email address and select their access level from the dropdown menu.

For an administrator troubleshooting:

User creation failures logged as USER_CREATE_ERROR typically indicate duplicate email addresses or invalid role values. Check the request payload in the error details.

Same underlying feature. Three different documents. Each serves its audience because the writer understood who would read it.

Identifying Your Audience¶

Start by identifying who actually uses your documentation. This seems obvious but frequently goes undone.

Primary Questions¶

Ask these questions for every documentation project:

Who are the users?

• Job titles and roles
• Industries and contexts
• Experience levels
• Geographic and cultural backgrounds

What is their goal?

• What task are they trying to complete?
• What problem are they trying to solve?
• What decision are they trying to make?

What do they already know?

• Technical background
• Product familiarity
• Domain expertise

What is the context of use?

• Where will they read this? (desk, data center, factory floor)
• What device will they use?
• How much time do they have?
• Are they learning, doing, or troubleshooting?

Information Sources¶

Gather audience information from multiple sources:

Direct Research

• User interviews
• Surveys and questionnaires
• Usability testing observations
• Support interactions

Indirect Sources

• Customer support data (common questions, confusion points)
• Analytics (search queries, popular pages, time on page)
• Product usage data
• Sales and customer success team insights
• Community forums and discussions

Stakeholder Input

• Product managers (target market, use cases)
• Engineers (technical requirements, common errors)
• Support teams (frequent issues)
• Training teams (learning challenges)

Audience Segmentation¶

Most products have multiple audience segments. Identify each distinct group:

By Role

• End users
• Administrators
• Developers
• Evaluators/decision-makers

By Experience

• New users learning the product
• Experienced users seeking reference
• Power users pushing boundaries

By Task

• Setup and configuration
• Daily operations
• Troubleshooting
• Integration and customization

Document which segments need which content. Some documentation serves all users; other content targets specific segments.

Creating User Personas¶

Personas transform abstract audience segments into concrete, memorable representations. They help writers make consistent decisions by providing a mental model of real users.

Persona Components¶

Effective personas include:

Demographics

• Name (fictional but realistic)
• Job title and responsibilities
• Industry and company context
• Years of experience

Technical Profile

• Technical skill level
• Relevant tools and technologies used
• Learning preferences
• Access to resources

Goals and Tasks

• Primary objectives
• Common tasks
• Success criteria
• Constraints and challenges

Information Needs

• What they need from documentation
• How they prefer to consume information
• What frustrates them
• What they already know

Example Persona¶

Dana Martinez - Integration Developer

Dana is a mid-level software developer at a healthcare technology company. She has five years of experience with Java and Python and is comfortable reading API documentation and code samples.

Dana needs to integrate our payment API into her company's patient billing system. She wants clear endpoint documentation, complete request/response examples, and information about error handling. She dislikes documentation that wastes time with concepts she already knows or omits details she needs.

Dana typically works at her desk with multiple monitors, keeping documentation open alongside her IDE. She scans for relevant sections rather than reading sequentially. She values accuracy and completeness over friendliness.

Key needs: Complete API reference, working code samples, error handling documentation, webhook documentation

Using Personas¶

Reference personas when making documentation decisions:

• "Would Dana need this background explanation, or would it waste her time?"
• "How would Dana search for this information?"
• "What context would Dana have when reading this?"

Personas keep abstract "users" concrete. They prevent writing for imaginary experts who need no explanation or imaginary novices who need everything explained.

Persona Limitations¶

Personas simplify reality. Remember their limitations:

• Real users vary more than personas suggest
• Personas can become stereotypes if not based on research
• Multiple personas may need the same documentation differently
• Personas require updates as products and markets change

Use personas as tools, not constraints. They guide decisions but do not make them.

Assessing Knowledge Levels¶

Documentation must meet users at their current knowledge level—neither over-explaining what they know nor assuming knowledge they lack.

Knowledge Dimensions¶

Users have varying knowledge across several dimensions:

Domain Knowledge

Understanding of the subject area (networking, accounting, medical devices) independent of your specific product.

Product Knowledge

Familiarity with your specific product, its features, and its interface.

Technical Knowledge

General technical skills (programming, system administration, data analysis) applicable across products.

Task Knowledge

Experience with the specific task they are trying to accomplish, regardless of product.

Users may be experts in some dimensions and novices in others. A seasoned network engineer may be a novice with your specific monitoring tool. A product expert may be unfamiliar with the regulatory compliance context for their new task.

Assessing Levels¶

For each audience segment, assess knowledge levels:

This assessment guides content decisions:

• What to explain vs. assume
• How much context to provide
• What prerequisite links to include
• What terminology requires definition

Progressive Disclosure¶

When audiences have varying knowledge levels, use progressive disclosure:

• Lead with essential information everyone needs
• Provide optional depth for those who want it
• Link to prerequisite content for those who need it
• Use expandable sections for advanced details

This approach serves multiple knowledge levels without forcing any user through irrelevant content.

Tailoring Content¶

Audience analysis becomes valuable when it shapes content decisions.

Vocabulary¶

Match vocabulary to audience knowledge:

For developers:

The API uses OAuth 2.0 with PKCE for authentication. Implement the authorization code flow with a SHA-256 code verifier.

For administrators:

Users log in with their company credentials through single sign-on. The system uses industry-standard security protocols.

Same concept, different vocabulary, appropriate to each audience.

Depth¶

Adjust explanation depth:

For experts:

Configure the TTL based on your cache invalidation requirements.

For novices:

Set the TTL (Time To Live) to control how long items stay in the cache before expiring. Shorter values mean more frequent refreshes but more load on your servers; longer values reduce load but may show stale data.

Experts need reference; novices need explanation.

Structure¶

Organize content to match how users work:

For task-oriented users: Step-by-step procedures with clear outcomes

For reference-oriented users: Alphabetical or categorical organization with quick scanning

For learning-oriented users: Conceptual progression building understanding

Format¶

Choose formats that work for your audience:

Developers often prefer:

• Code samples they can copy
• API references they can scan
• Command-line examples

Business users often prefer:

• Visual guides with screenshots
• Numbered procedures
• Video walkthroughs

Field technicians often prefer:

• Quick reference cards
• Mobile-friendly formats
• Visual troubleshooting guides

Validating Assumptions¶

Audience analysis involves assumptions. Validate them.

Feedback Mechanisms¶

Build in feedback loops:

• Page ratings ("Was this helpful?")
• Comments and suggestions
• Search analytics (what do users look for?)
• Support ticket analysis

Testing¶

Test documentation with real users:

• Task completion testing: Can users accomplish goals?
• Comprehension testing: Do users understand content?
• Findability testing: Can users locate information?

Iteration¶

Audience analysis is ongoing:

• Review feedback regularly
• Update personas as products and markets evolve
• Adjust content based on usage data
• Revalidate assumptions periodically

Common Mistakes¶

Avoid these audience analysis failures:

Writing for yourself Writers often assume audiences share their knowledge. They do not.

Assuming homogeneity "Our users are developers" ignores variation among developers.

Skipping research Assumptions without evidence lead to documentation that misses the mark.

Ignoring context Users reading documentation at 2 AM during an outage have different needs than users exploring features during evaluation.

Static analysis Audiences change. Products change. Continuous analysis is necessary.

Summary¶

Audience analysis is the foundation of effective documentation. Identify who your users are, understand their knowledge levels and goals, create personas to guide decisions, and tailor content to serve real user needs.

Without audience analysis, documentation becomes guesswork. With it, documentation becomes a tool that genuinely helps users accomplish their goals.

Next: Clarity and Conciseness covers writing techniques that make content accessible to your identified audience.