I am Xavier
/now
pkm
- building a
personal knowledge management system - I 🩷 Obsidian
play
- playing TTRPG games
- writing about them
learning
- learning and understanding AI
- experimenting with AI tools
reading
- Tiny Experiments
#neuroscience - Memory Lane
#neuroscience - Your AI Roadmap
#ai #work - Mark of the Fool
#litrpg
Disclaimer
- While the concepts and techniques discussed are based on current trends and best practices, the field of AI and its applications to documentation are rapidly evolving.
- Examples and case studies are provided for illustrative purposes and may not represent typical results.
Who's Reading Your Documentation?
Understanding Dual Audiences
- The rise of AI agents as documentation consumers
- How humans vs. AI process documentation
- AI agent types and their documentation needs
- Core elements for dual-audience documentation
- Real-world case studies
Evolution of Doc Consumers
Human Readers Only
(Pre-20th Century)
Searchable Knowledge Bases
(Mid-20th Century to Early 21st Century)
Passive AI Systems
(Early 21st Century)
Active AI Agents
(Current & Emerging Era)
What Are AI Agents?
Autonomous AI systems that can perceive, decide, and act
- Autonomy (limited human intervention)
- Task orientation
- Tool usage capabilities
- Persistent state
Why This Matters Now
- AI agents are entering production environments
- Documentation is becoming executable
- Poorly designed docs can lead to incorrect agent actions
- Documentation designed for both audiences creates multiplied value
How Humans Read Docs
- Scanning and skimming patterns
- Emotional responses influence comprehension
- Non-linear navigation (jumping between sections)
- Bring real-world context and inference
- Tolerate ambiguity and fill gaps with experience
How AI Processes Docs
- Tokenization and pattern matching
- Linear or link-directed processing
- Limited contextual understanding
- Literal interpretation dominates
- Struggles with implicit information
- Depends heavily on consistent structure
The Critical Difference
Interpretation → Planning → Execution
Intuition fills documentation gaps
Intuition fills documentation gaps
Parsing → Decision trees → Direct execution
Requires explicit instructions for gaps
Requires explicit instructions for gaps
Types of AI Agents
- Assistive agents: Help navigate documentation (chatbots)
- Workflow agents: Execute processes based on procedures
- Development agents: Write/modify code based on specifications
- Operational agents: Maintain systems based on runbooks
- Integration agents: Connect systems based on API docs
Instruction 🆚 Code
Docs as Instruction
Documentation describes; code executes
Docs as Code
For AI agents, documentation IS executable
Critical Doc Needs for Agents
- Decision boundaries: Explicit conditions for agent actions
- Tool specifications: Precise descriptions of available tools
- Success criteria: Clear definitions of expected outcomes
- Error handling: Comprehensive guidance for exceptions
- Constraints: Explicit limitations on agent actions
Documentation Hierarchy
- Strategic level: Purpose and context () -
WHY - Tactical level: Procedures and workflows ( & ) -
WHAT - Operational level: Specific commands and parameters (primarily ) -
HOW
Divergent Doc Needs
| Aspect | Human Readers | AI Readers |
|---|---|---|
| Narrative | Appreciate storytelling | Prefer structured data |
| Information | Can work with implicit info | Need explicit statements |
| Repetition | Tire of repetition | Benefit from consistency |
| Precision | Appreciate variation | Require exact patterns |
| Cross-references | Handle contextual jumps | Need explicit links |
Case Studies
API Documentation
Bad Example
API Endpoint: /data
Method: POST
Parameters: id, data
Returns: JSON
Good Example
## /data (POST)
This endpoint allows you to submit data to the system.
**Request Body (JSON):**
```json
{
"id": "user123", // Unique identifier for the user
"data": {
"value1": 10,
"value2": "example"
}
}
**Response (JSON):**
```json
{
"status": "success",
"message": "Data submitted successfully"
}
Error Codes:
- 400 Bad Request: Invalid input data.
- 401 Unauthorized: Missing or invalid authentication token.
Runbooks
Product Documentation
Model Context Protocol https://modelcontextprotocol.io/llms-full.txt
Key Takeaways
- Documentation is now consumed by both humans and AI agents
- AI agents read differently and take direct action on documentation
- Different agent types have specific documentation needs
- Effective dual-audience documentation balances human readability with machine actionability
- The line between documentation and code is blurring
Questions?
/
Practical Strategies and Implementation
- Structured documentation approaches
- Documentation for AI agent capabilities
- Converting documentation for dual audiences
- Practical examples workshop
- Tools and testing strategies
- Future trends in technical writing
Structured Documentation Approaches
- Semantic HTML and meaningful structure
- Consistent formatting patterns
- Clear hierarchical organization
- Machine-readable metadata
- Separation of concerns (purpose, process, details)
The Documentation Spectrum
Narrative, context-rich, flexible
Structured narrative with embedded patterns
Rigid structure, explicit patterns, comprehensive
Practical Techniques
Layered Documentation
Human entry points
- Conceptual overviews
- Task-based guides
- Troubleshooting scenarios
AI entry points
- Schema definitions
- Parameter references
- Decision trees
Structured Task Flows
- Task objective (human-friendly)
- Prerequisites (explicit list)
- Step-by-step procedure (numbered, detailed)
- Expected outcomes (explicit success criteria)
- Troubleshooting (structured decision tree)
Machine-Readable Metadata
<div class="procedure" data-task-type="configuration" data-system="billing">
<h3>Configure Payment Gateway</h3>
<p class="objective">Set up the payment gateway to process customer transactions.</p>
<ul class="prerequisites">
<li data-prerequisite-type="account">Active merchant account</li>
<li data-prerequisite-type="permission">Administrator access</li>
</ul>
<!-- Steps and other content -->
</div>
Documenting for AI Agents
- Task specification formats
- Permission frameworks
- Tool integration specifications
- State management documentation
- Error handling protocols
Permission Framework Example
agent_permissions:
billing_system:
read:
- customer_records
- payment_history
- subscription_status
write:
- payment_status
- subscription_status
restricted:
- credit_card_numbers
- customer_passwords
actions:
allowed:
- send_payment_reminder
- update_subscription
requires_confirmation:
- cancel_subscription
- issue_refund
prohibited:
- delete_customer_account
- modify_pricing
Convert Docs
Step 1: Audit current documentation structure and patterns
Step 2: Identify AI-unfriendly elements
Step 3: Add structure and explicit patterns
Step 4: Incorporate machine-readable metadata
Step 5: Test with both audiences
Step 6: Iterate based on feedback
Common AI-Unfriendly Elements
- Implied steps ("simply configure the settings")
- Ambiguous success criteria ("should work correctly")
- Contextual references without explicit links
- Unstructured troubleshooting tips
- Inconsistent terminology
- Incomplete parameter descriptions
- Missing error scenarios
Example: Documentation Transformation
Before
"To configure email notifications, go to the Settings page and adjust the notification preferences as needed. You can customize which events trigger emails. Make sure to save your changes when done."
After
<div class="procedure" data-task-type="configuration" data-system="notifications">
<h3>Configure Email Notifications</h3>
<p class="objective">Set up which events trigger email notifications to users.</p>
<div class="prerequisites">
<h4>Prerequisites:</h4>
<ul>
<li>Administrator or Manager role</li>
<li>Email server configured</li>
</ul>
</div>
<div class="procedure-steps">
<h4>Steps:</h4>
<ol>
<li>Navigate to Settings > Notifications > Email Configuration.</li>
<li>In the "Event Triggers" section, check the boxes for events that should trigger emails:
<ul>
<li>New user registration</li>
<li>Password reset</li>
<li>Order confirmation</li>
<li>Shipping notification</li>
<li>Account status change</li>
</ul>
</li>
<li>For each selected event, configure frequency using the dropdown menu:
<ul>
<li>Immediate</li>
<li>Hourly digest</li>
<li>Daily digest</li>
</ul>
</li>
<li>Click the "Save Configuration" button at the bottom of the page.</li>
</ol>
</div>
After
<div class="expected-outcome">
<h4>Expected Outcome:</h4>
<p>A green confirmation message appears stating "Email notification settings saved successfully."</p>
</div>
<div class="troubleshooting">
<h4>Troubleshooting:</h4>
<ul>
<li><strong>If no confirmation message appears:</strong> Refresh the page and try again.</li>
<li><strong>If error "Email server not responding" appears:</strong> Verify email server settings under Settings > System > Email Server.</li>
</ul>
</div>
</div>
Testing Documentation with AI
- Validate structure with schema validation tools
- Test with LLM-based assistants as proxies
- Create scenario-based validation tests
- Implement documentation unit tests
- Peer review with AI and automation focus
- Track AI consumption metrics
Tools for Dual-Audience Docs
- Structured authoring tools: Markdown, DITA, DocBook, Sphinx
- Schema validation: JSON Schema, XML Schema
- Metadata frameworks: JSON-LD, Schema.org
- Documentation testing: Vale, Markdownlint
- AI-assisted documentation: GitHub Copilot, Claude
- Machine-readable formats: OpenAPI, AsyncAPI, llms.txt
Future Trends *
- AI-first documentation that generates human views
- Executable documentation linked to live systems
- Interactive documentation that adapts to audience needs
- Dynamic verification and testing of documentation
- Collaborative authoring between humans and AI
- Cross-system documentation standards for agents
* Very speculative
Where to Start
- Begin with high-value, automation-ready documentation
- Implement consistent structure before adding metadata
- Focus on explicit task flows and procedures first
- Create small pilot projects to demonstrate value
- Develop style guides that address dual audiences
- Build testing into your documentation process
Key Takeaways
- Documentation for dual audiences is about balance, not compromise
- Structured, explicit content benefits both humans and AI
- Layered approaches satisfy different entry points and needs
- Converting existing documentation can be done incrementally
- Testing is essential for ensuring both audiences are served
- This is a transformation, not just an add-on to existing practices
Questions?
Books for further reading
- Emphasizes the power of human-AI collaboration.
- Advocates for the importance of writing in an AI world.
- Explores the societal impact of emerging technologies, including AI.
- Discusses the formation of powerful networks and collaborations in the age of AI.
Tools
- Slides (via: RevealJS)
- Website (via: Eleventy)
- Neural (via: Coolors)
- Geo & Offside (via: Google Fonts)
- Icons (via: Lucide)
Slides available at Docs for AI