In my recent talk, Documentation for AI & Humans, I discussed how documentation is increasingly being consumed not just by people, but also by AI. I had a slide titled: Documentation as Instruction vs. Documentation as Code.

After the talk, some folks have asked if I could explain a bit more about the idea. This concept seemed to really resonate with the audience, and I’ve been thinking about how to articulate it more clearly.

Traditionally, we’ve viewed documentation as description and code as execution – two separate domains. But for AI agents, this line is blurring. Documentation is increasingly becoming executable – it’s not just describing what should happen, but actually serving as the instruction set that agents follow.

When an operational agent uses a runbook to resolve an incident, it treats that documentation as live code. When a development agent uses API documentation for integration, parameter descriptions become specifications for action.

I find this shift fascinating because our words are literally becoming instructions for both human and machine intelligence.

Well-structured documentation acts as a program, parsed and executed by AI agents to achieve specific goals.

Why structure matters

Consider an AI-powered customer support chatbot unable to answer a user query about a specific API function because the documentation is a wall of unstructured text. Conversely, picture the same chatbot instantly providing the correct information from clearly structured, machine-readable content.

Have you ever experienced the frustration of searching through poorly structured documentation? Now imagine being an AI trying to do the same thing.

This illustrates why structure is paramount. AI agents require documentation for information, procedural understanding, and data comprehension.

Consistent, predictable information is essential for AI. Automation workflows rely on documentation for tasks like testing and deployment. Structure enables efficient data extraction and repurposing by AI, enhancing its utility. Crucially, machine-readable documentation improves human readability.

Structure fosters clarity, consistency, and maintainability, empowering everyone to find, understand, and update information effectively.

Key Strategies for Machine-Readable Output

To create documentation that serves both humans and agents, here are some practical strategies:

• Structured Procedures: Employ numbered steps for processes. This provides a direct, executable sequence for automation systems.
• Consistent Data: Use tables or structured lists for data like configurations. Clearly labeled formats enable automated parsing and extraction for system operations.
• Strategic Metadata: Embed relevant metadata (consistent headings, tags) to provide machines with essential context about information type and purpose, aiding AI navigation and utilization.
• Modular, Reusable Content: Break documentation into self-contained units. This allows efficient retrieval and repurposing by both humans and AI agents across contexts.

The Changing Role of Technical Writers

As documentation becomes foundational for intelligent systems, the technical writer’s role is transforming, directly impacting our ability to create executable knowledge. Here are some key shifts, their challenges, and mitigation methods:

Technical Writers as Information Architects

• Shift: From linear author to designer of structured, actionable information ecosystems.
• Challenge: Lack of formal training in information architecture for machine actionability.
• Mitigation:
  • Invest in training on content modeling and data structuring for machine parsing and execution.
  • Collaborate with IA/UX professionals.
  • Adopt structured authoring for executable components.

Embracing Data-Centric Documentation

• Shift: From text-centric to data-centric documentation as a source of executable data.
• Challenge: Understanding how to model information for direct AI and automation use. Traditional workflows may not support this.
• Mitigation:
  • Develop data modeling skills for AI algorithms and automation scripts.
  • Explore structured data formats (JSON, YAML) as direct sources for executable configurations and inputs.
  • Experiment with knowledge graphs for direct AI querying.

Mastering Metadata and Semantics

• Shift: From basic tagging to strategic application of metadata and semantics for machine understanding and action.
• Challenge: Knowing relevant standards and ensuring consistent application for AI processing. Poor metadata hinders machine actionability.
• Mitigation:
  • Learn metadata standards (e.g., Dublin Core) and semantic vocabularies (e.g., Schema.org) for machine annotation.
  • Establish clear metadata governance for AI consumption.
  • Utilize AI-aware metadata management tools.

Cultivating Automation Awareness

• Shift: From manual documentation to understanding and leveraging automation for documentation and documentation-driven automation.
• Challenge: Identifying automation opportunities and a potential resistance to new technologies.
• Mitigation:
  • Encourage exploration of scripting (e.g., Python) and automation tools for interacting with structured documentation.
  • Identify automatable documentation tasks and explore “docs as code” concepts.

Fostering Cross-Disciplinary Collaboration

• Shift: From isolated documentation creation to integrated collaboration with development and AI teams.
• Challenge: Breaking down silos and establishing effective communication for shared understanding of human and machine needs.
• Mitigation:
  • Establish regular, shared workflows with development and AI teams, emphasizing documentation as a shared, executable asset.
  • Involve technical writers early to understand system requirements for both human users and AI agents.
  • Promote mutual understanding across teams.

Well-structured, machine-readable documentation is paramount for intelligent systems and automation. Technical writers are central to this foundation, ensuring information is both user-friendly and AI-ready. By embracing these evolving practices, technical writers are not just adapting; they are building the executable knowledge base for the future of human-machine interaction.

So where does all this leave us? At the center of an AI revolution, but with a twist—we’re not being replaced by AI; we’re teaching AI how to understand our domains.

Well-structured, machine-readable documentation isn’t just nice to have anymore. It’s the foundation upon which intelligent systems are built. When we create clear, structured, consistent information, we’re essentially creating the neural pathways through which AI understands our products, services, and processes.

The future of technical communication isn’t just instructing humans—it’s instructing the machines that serve them.

Question

What step will you take today to make your documentation more executable?