Technical Writing and Documentation 101: Audience Analysis (Personas, Skill Levels, Use Cases)

Audience Analysis (Personas, Skill Levels, Use Cases)

Audience Analysis for Technical Writers: Personas, Skill Levels, and Use Cases

A Practical Study Guide for Aspiring & Modernizing Technical Writers

What This Is

Audience analysis is the process of identifying who will use your documentation, what they already know, and why they’re reading it. Without this, even the most accurate docs can fail—like a payment gateway’s API reference that assumes all readers are senior backend engineers, when half are frontend devs integrating a checkout button. Good audience analysis ensures your docs are useful, not just correct.

Real-world example:
- Stripe’s API docs segment content for developers (code examples, SDKs) vs. business users (dashboard guides, billing explanations).
- AWS’s "Getting Started with EC2" assumes zero cloud knowledge, while their VPC Networking Guide targets architects with advanced networking experience.

Key Terms & Tools

• Personas: Fictional but data-backed profiles of your users (e.g., "Frontend Fiona," a junior dev who needs copy-paste examples). Tools: Xtensio, Miro, or even a simple Google Doc template.
• Skill Levels:
• Beginner: Needs step-by-step instructions, glossary terms, and minimal jargon.
• Intermediate: Wants best practices, troubleshooting tips, and concise explanations.
• Expert: Prefers reference material, edge cases, and performance considerations.
• Use Cases: The specific tasks users want to accomplish (e.g., "Deploy a container," "Debug a 500 error"). Tools: User interviews, support tickets, or analytics (e.g., Google Analytics for docs site traffic).
• User Stories: Short, action-oriented statements like "As a data scientist, I want to export my model so I can deploy it in production." Format: As a [persona], I want to [task] so that [goal].
• Docs-as-Code: Treating docs like code—stored in Git (e.g., GitHub/GitLab), written in Markdown/AsciiDoc, and built with tools like Sphinx, Docusaurus, or MkDocs.
• DITA (Darwin Information Typing Architecture): An XML-based standard for modular, reusable docs. Used in enterprise tools like Oxygen XML Editor.
• OpenAPI/Swagger: A spec for describing REST APIs. Tools like Swagger UI or Redoc auto-generate interactive docs from YAML/JSON files.
• Analytics for Docs: Tools like Google Analytics, Plausible, or PostHog track which pages users visit, how long they stay, and where they drop off.
• Feedback Loops: Ways to gather user input (e.g., "Was this helpful?" buttons, GitHub issues, or surveys via Typeform).
• Minimal Viable Documentation (MVD): The smallest set of docs needed to unblock users. Prioritize based on audience needs (e.g., a "Quick Start" guide before a full API reference).
• Progressive Disclosure: Showing only the most relevant info upfront, with links to deeper details (e.g., a "Learn more" button for advanced topics).

Step-by-Step Process Flow

1. Gather Data: Who Are Your Users?

Actions:
- Interview stakeholders: Talk to product managers, support teams, and sales. Ask: - "Who uses this product?" - "What are their biggest pain points?" - "What questions do you get most often?" - Mine existing data:
- Support tickets (e.g., Zendesk, Intercom) - Community forums (e.g., Stack Overflow, Discord, Slack) - Analytics (e.g., top-visited pages, bounce rates) - Create a user matrix: List roles (e.g., "DevOps Engineer," "Data Analyst") and their goals.

Example:
| Role | Skill Level | Use Case | Pain Points | |--------------------|-------------|-----------------------------------|---------------------------------| | Frontend Developer | Intermediate| Integrate Stripe checkout | Confused by OAuth flow | | DevOps Engineer | Expert | Deploy API in Kubernetes | Needs performance benchmarks |

2. Build Personas (Keep It Practical)

Actions:
- Start with 2–3 personas (e.g., "Backend Ben," "Junior Jamie"). Avoid overcomplicating.
- Include:
- Role/Title (e.g., "Full-Stack Developer") - Goals (e.g., "Ship a feature in 2 days") - Frustrations (e.g., "Docs assume I know Kubernetes") - Preferred Tools (e.g., "Uses VS Code and Postman") - Where They Find Docs (e.g., "Google → Stack Overflow → Official Docs") - Validate with real users: Share personas with a few users and ask, "Does this sound like you?"

Example Persona:

Name: "Frontend Fiona" Role: Junior Frontend Developer at a startup Goals:
- Integrate a payment API without breaking the app.
- Find copy-paste code examples.
Frustrations:
- Jargon-heavy docs ("What’s an idempotency key?").
- No error-handling examples.
Tools: VS Code, Chrome DevTools, React.
Where She Finds Docs: Google → MDN → Stack Overflow → Official API docs.

3. Map Use Cases to Personas

Actions:
- List top 3–5 use cases per persona. Example for "Frontend Fiona": 1. Add a "Pay Now" button to a React app.
2. Handle errors (e.g., "Card declined").
3. Test the integration locally.
- Prioritize docs based on frequency/impact. Example: - High priority: "Add a payment button" (many users, critical for adoption).
- Low priority: "Customize the checkout UI" (few users, niche need).
- Create a content matrix:

4. Write for the Audience (Not for Yourself)

Actions:
- Adjust tone and depth:
- Beginner: Explain concepts (e.g., "What is an API?"), use analogies, and avoid acronyms.
- Expert: Assume knowledge, focus on edge cases, and link to specs.
- Choose the right doc type:
- Tutorial: Teaches concepts by building (e.g., "Build a Weather App with Our API").
- How-To Guide: Solves a specific problem (e.g., "Fix a 403 Error in Your API Request").
- Reference: Dry, factual info (e.g., API endpoint descriptions).
- Explanation: Deep dives (e.g., "How Our Authentication Works").
- Test with real users: Ask a junior dev to follow your tutorial. If they get stuck, revise.

Example:
- For "Frontend Fiona":
```markdown ## Add a Payment Button (React) Prerequisites: Basic React knowledge. You’ll need a Stripe account.

1. Install the Stripe SDK:
   bash
npm install @stripe/stripe-js

2. Copy this code into your App.js:
   ```jsx
   import { loadStripe } from '@stripe/stripe-js';

   const stripePromise = loadStripe('your_publishable_key');

   function CheckoutButton() {
   const handleClick = async () => {
   const stripe = await stripePromise;
   const { error } = await stripe.redirectToCheckout({
   lineItems: [{ price: 'price_123', quantity: 1 }],
   mode: 'payment',
   successUrl: 'https://your-site.com/success',
   cancelUrl: 'https://your-site.com/canceled',
   });
   if (error) console.error(error);
   };

   return Pay Now; } 3. Replace `your_publishable_key` with your [Stripe API key](link). - For "DevOps Engineer":
   ```markdown ## Deploying the API in Kubernetes Prerequisites: kubectl, Helm, and a running K8s cluster.

3. Add the Helm repo:
   bash
helm repo add our-api https://charts.our-api.com

4. Deploy with custom resource limits:
   yaml
# values.yaml
resources:
limits:
cpu: "2"
memory: "4Gi"
bash
helm install our-api our-api/our-api -f values.yaml
5. Monitor performance with:
   bash
kubectl top pods ```

5. Validate and Iterate

Actions:
- A/B test docs: Try two versions of a page (e.g., one with a video, one with code snippets) and track which performs better.
- Gather feedback:
- Add a "Was this helpful?" button (tools: FeedbackFish, Delighted).
- Monitor GitHub issues or community forums for questions.
- Update personas: Revisit them every 6 months (or after major product changes).

Common Mistakes

Tech Writing Interview / Portfolio Tips

What Hiring Managers Look For:

1. Audience awareness: Can you explain why you wrote a doc a certain way? Example:
2. "I added a ‘Prerequisites’ section because our analytics showed 30% of users didn’t have Python installed."
3. Tool proficiency: Know the tools your target company uses (e.g., if they use Docusaurus, mention your experience with Markdown + React).
4. Portfolio pieces that show range:
5. A tutorial (e.g., "Build a Slack Bot in 10 Minutes").
6. A reference doc (e.g., API endpoint with OpenAPI spec).
7. A troubleshooting guide (e.g., "Fixing Common Docker Errors").
8. Tricky distinctions to know:
9. Tutorial vs. How-To Guide:
   • Tutorial: Teaches concepts by building (e.g., "Build a To-Do App with React").
   • How-To Guide: Solves a specific problem (e.g., "Fix a CORS Error in Your API").
10. Swagger UI vs. Redoc:
    • Swagger UI: Interactive, good for testing APIs.
    • Redoc: Cleaner UI, better for reference docs.
11. Conceptual Doc vs. Reference:
    • Conceptual: Explains why (e.g., "How OAuth Works").
    • Reference: Explains what (e.g., "OAuth Endpoint Parameters").

Portfolio Tips:

• Show your process: Include a README in your portfolio repo explaining:
• How you analyzed the audience.
• What tools you used (e.g., "Wrote in Markdown, built with Docusaurus").
• How you gathered feedback.
• Use real-world examples: If you don’t have work samples, create docs for open-source projects (e.g., GitHub’s "Good First Issues").
• Highlight collaboration: Mention how you worked with engineers (e.g., "Reviewed API specs with the backend team").

Quick Check Questions

1. Scenario: A developer complains that the API docs are outdated. How would you ensure docs stay in sync with code?
2. Answer: Implement docs-as-code (store docs in Git, auto-generate from OpenAPI specs, and require doc updates in PRs).

3. Why: This ties docs to the codebase, so they’re updated alongside features.

4. Scenario: Your analytics show that beginners drop off on the "Authentication" page. What’s one way to improve it?

5. Answer: Add a progressive disclosure section (e.g., "Basic Auth" first, then "OAuth for Advanced Users") or a video walkthrough.

6. Why: Beginners need simpler entry points before diving into complexity.

7. Scenario: You’re writing docs for a CLI tool. How do you decide whether to include a tutorial or a how-to guide?

8. Answer: Use a tutorial if users need to learn concepts (e.g., "Build Your First CLI App"), and a how-to guide for specific tasks (e.g., "Debug a Permission Error").
9. Why: Tutorials teach by doing; how-to guides solve immediate problems.

Last-Minute Cram Sheet

1. Personas: Fictional users based on real data (e.g., "DevOps Dave," "Junior Jamie").
2. Skill levels: Beginner (hand-holding), Intermediate (best practices), Expert (reference).
3. Use cases: The tasks users want to accomplish (e.g., "Deploy a container").
4. Docs-as-code: Store docs in Git, write in Markdown, build with static site generators.
5. OpenAPI: YAML/JSON spec for REST APIs. Tools: Swagger UI, Redoc.
6. DITA: XML-based standard for modular docs (used in enterprise).
7. Progressive disclosure: Show basics first, link to advanced topics.
8. ⚠️ Tutorial ≠ How-To Guide: Tutorials teach concepts; how-to guides solve problems.
9. Feedback loops: "Was this helpful?" buttons, GitHub issues, surveys.
10. MVD (Minimal Viable Documentation): Start with the smallest useful docs, then expand.