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.

Hierarchical (Top-Down) Organization

Structure:
This model arranges information from general to specific. Think of it like a tree: broad topics (like “Getting Started”) sit at the top, and more detailed topics (like “Installing the API Client” or “Configuring Settings”) branch off beneath them. It’s ideal when content builds on foundational knowledge or when users need an overview before diving deeper.

Best for:
Large documentation sets with clear parent-child relationships or nested categories.

Task-Based Organization

Structure:
Content is grouped based on what users are trying to do. Each section focuses on a specific action or goal, such as “Set Up Your Environment” or “Retrieve User Data.” This approach works like a checklist, guiding users through common tasks with clear, step-by-step instructions.

Best for:
User guides, tutorials, onboarding flows, and documentation meant to support specific workflows.

Role-Based Organization

Structure:
Documentation is segmented by user type or persona. For example, separate sections might exist for Developers, Admins, Analysts, or End Users. Each role has access to content relevant to their responsibilities, reducing confusion and streamlining the reading experience.

Best for:
Products used by multiple audiences with distinct responsibilities and goals.

Feature-Based Organization

Structure:
Information is grouped according to the product’s individual features or modules. Each section covers one feature in detail—like “Authentication,” “Notifications,” or “Analytics.” This allows users to dive directly into the areas most relevant to them without sifting through unrelated content.

Best for:
Feature-rich or modular platforms where users often focus on one capability at a time.

Process/Procedure-Based Organization

Structure:
Content is laid out in the order a user would follow to complete a specific process. It’s like a recipe: Step 1, Step 2, Step 3. Each step builds on the last, helping users move through a sequence without missing critical actions.

Best for:
Install guides, setup flows, end-to-end tutorials, and workflows that require a linear progression.

Prompt

Act as an expert in technical documentation and information architecture. Analyze the following list of documentation topics/pages for optimal structuring. Your goal is to design an intuitive and effective documentation layout for a target audience of [insert target audience, e.g., new developers].

Perform the following tasks:
1. Recommend the most appropriate organizational model — choose from: Hierarchical, Task-Based, Role-Based, Feature-Based, or Process-Based — and justify your choice based on the needs of the target audience.
2. Propose a logical grouping and hierarchy of the documentation topics using clear and relevant section titles.
3. Suggest interlinking strategies to enhance content discoverability, navigation, and user flow.

[Insert Documentation Topics Here]

How to use

1. Define the Target Audience
   Replace [insert target audience, e.g., new developers] with a specific audience type, such as:

   • "internal DevOps engineers"

   • "enterprise customers with limited technical background"

   • "first-time API users"

2. Insert Your Topics
   Replace [Insert Documentation Topics Here] with your own list of documentation topics or pages. Each item should be a concise topic title (e.g., "Getting Started", "Creating a Webhook", "Monitoring API Errors").

3. Submit the Prompt to ChatGPT (or your preferred LLM)
   Paste the final, filled-in prompt into the prompt window and run the query. You’ll receive:

   • A suggested documentation structure

   • A recommended organizational model and its justification

   • Interlinking strategies to improve UX/navigation

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.

Understanding Your Audience and Purpose

Before any documentation is drafted, a clear understanding of its purpose and intended audience is paramount. The purpose can vary widely, from explaining a complex system to new team members, providing detailed instructions for equipment maintenance, or outlining critical safety procedures. The audience, in turn, dictates the language, level of detail, and specific content that should be included.

Clarity, Conciseness, and Consistency

These three principles are synergistic, forming the bedrock of high-quality technical writing.

• Clarity: Documentation must be easy to understand. This involves using simple, plain language and avoiding unnecessary jargon unless it is clearly defined within the document. Complex information should be broken down into smaller, digestible chunks, often utilizing headings, subheadings, and bullet points. Employing active voice makes sentences more concise and direct, enhancing readability.

• Conciseness: Get straight to the point. Eliminate superfluous words and redundancies, and use bullet points or lists to facilitate quick scanning and focus on essential details. Keeping paragraphs to four to six lines and sentences to 10-20 words significantly improves readability.

• Consistency: Maintain a uniform tone, writing style, formatting (such as fonts, headings, and bullet points), and standardized terminology throughout the document and across the entire documentation suite. Leveraging established guides like Google's developer documentation style guide or the Microsoft Writing Style Guide is recommended.

  Prompt

  You are an expert technical editor. Review the following documentation draft with a focus on clarity, conciseness, and consistency. Provide specific, actionable feedback in each category.
  
  1. Clarity
  - Identify any undefined jargon, ambiguous language, or overly complex sentences.
  - Suggest simpler alternatives or improved structure for better understanding.
  
  2. Conciseness
  - Highlight redundant phrases, wordy constructions, or overly long paragraphs.
  - Recommend where bullet points or lists can be used to streamline information.
  - Suggest revisions to shorten or tighten the content without losing meaning.
  
  3. Consistency
  - Check for inconsistent tone, formatting (e.g., headings, bullets), or terminology.
  - Focus especially on consistent use of key terms like [specific terms comma separated]
  - Point out formatting mismatches or terminological drift, and propose standardized alternatives.
  
  Documentation Draft:
  [Paste your documentation draft here]
  

  How to use

  • Replace [specific terms] with important terms from your documentation (e.g., product names, feature terms, or domain-specific vocabulary).

  • Paste your draft content where indicated.

  • Run the full prompt in ChatGPT or your preferred LLM to receive a structured editorial review based on clarity, conciseness, and consistency.

  • Ideal for refining technical documentation, user guides, knowledge base articles, and internal docs.

  ---

  
  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.