[Prompt] – Usability Testing Docs with AI

Publishing docs isn’t the finish line—it’s just the first checkpoint.

One of the biggest struggles for writers is getting feedback early. Before the docs ever reach real users.

While this isn’t a replacement for testing with actual users, it can help catch usability issues, fill knowledge gaps, and tighten the flow of your documentation.

Most teams never get structured feedback, so the same issues keep slipping through:

• Did users find what they needed?

• Where did they get stuck?

• What’s still unclear?

👉 Here’s how to break that cycle:

1. Pick a persona (junior dev, senior dev, non-technical user).

2. Drop your docs into an LLM with a real-world task.

3. Watch where it hesitates, backtracks, or makes assumptions.

4. Fix those friction points before customers ever see them.

Try this prompt to simulate a real-world read-through:

Act as a {Persona} trying to use shared documentation to complete a task. Your goal is to behave like a real person.

Tell us if any parts:
- Felt too simple or overly guided
- Were vague, too basic, or missing critical details
- Could be improved to make the instructions easier to follow
- Required external help to complete the task

Be specific and share your suggestions in a structured manner

---

Persona Templates

Fabrizio Ferri uses YAML files to define detailed tendencies for each persona in his tool "Impersonaid."

Here are three examples you can start with from the repo:

01 Non_Technical_User

name: Non-technical user
description: A business user with limited technical knowledge who needs to understand and use a technical product.
expertise:
  technical: Novice
  domain: Moderate (in their business area)
  tools: Familiar with basic office software only
background:
  education: Business degree or equivalent
  experience: Several years in business operations, no technical experience
traits:
  patience: Low with technical concepts
  attention_to_detail: High for business impacts
  learning_style: Prefers visual guides and business-focused explanations
goals:
  - Understand how to use the product without technical details
  - Learn business benefits and use cases
  - Find quick start guides without jargon
preferences:
  documentation_style: Simple with screenshots and business examples
  communication: Non-technical language with business terminology

02 Expert_Developer

name: Expert developer
description: A senior developer with extensive experience in software development and technical documentation.
expertise:
  technical: Advanced
  domain: Expert
  tools: Proficient with a wide range of development tools and frameworks
background:
  education: Computer Science degree or equivalent
  experience: 10+ years of professional software development
traits:
  patience: Moderate
  attention_to_detail: High
  learning_style: Prefers comprehensive technical documentation with deep dives
goals:
  - Quickly understand system architecture
  - Find edge cases and limitations
  - Evaluate technical accuracy and completeness
preferences:
  documentation_style: Detailed with technical specifications
  communication: Precise technical language with proper terminology

03 Beginner_Developer

name: Beginner developer
description: A junior developer who is new to programming and the technology stack.
expertise:
  technical: Beginner
  domain: Limited
  tools: Basic understanding of development tools
background:
  education: Computer Science student or bootcamp graduate
  experience: Less than 2 year of professional experience
traits:
  patience: Low
  attention_to_detail: Moderate
  learning_style: Prefers step-by-step tutorials with examples
goals:
  - Understand basic concepts quickly
  - Find practical examples to learn from
  - Avoid complex technical jargon
preferences:
  documentation_style: Visual with clear examples
  communication: Simple and direct explanations

---

Instructions to Use

1. Choose a persona YAML file based on your target user.

2. Load your documentation and task into your preferred LLM.

3. Paste the prompt above, replacing {Persona} with the persona name.

4. Review the LLM’s feedback and look for signs of friction, confusion, or missing detail.

5. Apply fixes, and repeat as needed.

---

Important Note: AI as Your Co-pilot

AI is a powerful assistant, a "co-pilot," but it is not a replacement for human expertise, critical thinking, or oversight. Always review, refine, and fact-check AI-generated content. Your understanding of the project, audience, and technical accuracy remains paramount. Use AI to automate repetitive tasks, ensure consistency, and generate initial drafts, freeing you to focus on strategic planning and complex problem-solving.