How to Build Documentation for Coding Agents

TL;DR

Documentation for coding agents should use self-contained fragments, precise headings, compact context, deterministic metadata, and links that support fast retrieval. OpenWiki generates this structure through a simple CLI, adds files for agent guidance and GitHub Actions updates, and maintains the wiki automatically as the repository changes.

Transcript

Thank you everybody for coming. Um, like Shawn said, I'm going to be talking about our project OpenWiki, uh, how we built it, kind of the ideas behind it, how it works, uh, and where we're going next with it. So, what is OpenWiki? OpenWiki is a CLI that you can use to generate and maintain your, uh, repo documentation, uh, built specifically for ag... Read More

Key Insights

• OpenWiki is a command-line tool that generates and maintains repository documentation specifically for coding agents. The project treats code documentation as an initial, well-defined application of general-purpose agent memory that could later expand into other memory domains.
• Agent-focused documentation is structured differently from human-focused documentation because agents usually retrieve isolated fragments rather than read complete pages. Each fragment must therefore remain understandable by itself, use accurate headings, and avoid unnecessary content that could consume excessive context-window space.
• OpenWiki onboarding is designed around two simple stages: installation through NPM and wiki initialization through the CLI. The guided setup collects API keys, model configuration, and a wiki brief, then begins generating the documentation and supporting repository files automatically.
• OpenWiki creates Markdown files organized by narrowly focused topics rather than imposing a rigid universal directory structure. It always includes a Quickstart file, produces directory index files, links related documents, and gives the generating agent guidance about file quantity and size.
• Open Knowledge Format metadata adds deterministic YAML front matter to each wiki document. Fields such as type, title, description, resource tags, and timestamp enable agents to filter documents and locate relevant material more efficiently than unstructured repository-wide searching alone.
• Cross-linking helps coding agents discover related context after retrieving an initial fragment. Resource tags can connect documentation to source files, while ordinary Markdown links connect wiki pages, allowing an agent to follow references without loading an entire documentation collection into its context.
• The change log is designed for both agents and human reviewers. Agents can inspect documentation history, while developers can quickly understand what changed during the latest automatic update before deciding whether they need to examine individual modified wiki files.
• Early DeepSWE evaluations compare coding tasks performed with and without a generated OpenWiki. The reported direction of the results is more concise agent behavior, including fewer tool calls, searches, outputs, and tokens, while producing the same or better task outcomes.

Questions & Answers

Q: What is OpenWiki and what problem does it solve?

OpenWiki is an open-source command-line tool that generates and maintains repository documentation for coding agents. It addresses the problem that ordinary documentation is usually written for humans, while agents retrieve small pieces of context and need those pieces to be precise and self-contained. It also automates updates so developers do not have to continually refresh the wiki manually.

Q: How should documentation for coding agents be structured?

Documentation for coding agents should be divided into focused, self-contained fragments with predictable and accurate headings. Each file should cover a specific topic so an agent does not need to gather basic context from several unrelated locations. The content should also be compact, searchable, cross-linked, and free of unnecessarily large material that could overwhelm the agent's context window.

Q: Why is human-oriented documentation inefficient for coding agents?

Human-oriented documentation commonly provides narrative flow, background explanations, screenshots, videos, and connected pages intended to be read in sequence. Coding agents usually retrieve fragments rather than consume the complete narrative. A fragment that depends on earlier sections may therefore be unclear, while media or large encoded content can add substantial context without helping the agent complete its task.

Q: How does OpenWiki initialize documentation for a repository?

OpenWiki uses a CLI onboarding process that guides the developer through API keys, model configuration, and a wiki brief describing how the system should navigate the repository. It then generates the wiki, creates or modifies an AGENTS.md file instructing agents to consult it, and writes a GitHub Actions file that supports automatic updates after initialization.

Q: What files and directories does OpenWiki generate?

OpenWiki generates a collection of structured Markdown files and links between them. It always creates a Quickstart file that gives agents a high-level view of the repository and available documentation. It also creates topic-specific directories, an index file for each directory, deterministic metadata in document front matter, and a log file that records documentation changes.

Q: How does Open Knowledge Format improve document retrieval?

Open Knowledge Format adds predictable YAML front matter to Markdown documents, including fields such as type, title, description, resource tags, and timestamp. These deterministic fields let an agent filter for particular document types or tags instead of relying entirely on broad text search. The format also emphasizes connections among documentation pages and relevant source files.

Q: Why are indexes, links, and change logs important for agents?

Indexes let an agent quickly inspect the contents of a directory without opening every document. Links allow it to move from a retrieved fragment to related documentation or referenced source files. A change log provides the history and latest updates in one place, helping agents and human reviewers understand what changed before examining individual files in greater detail.

Q: What did the early DeepSWE evaluation indicate about OpenWiki?

The early evaluation used a subset of DeepSWE coding-agent tasks and compared runs without OpenWiki against runs performed after generating a wiki. The initial results pointed toward more concise agent operation, including fewer tool calls, fewer searches, fewer outputs, and lower token consumption, while still achieving the same or better results on the evaluated tasks.

Summary & Key Takeaways

• OpenWiki is an open-source CLI for generating and maintaining repository documentation designed specifically for coding agents. Its three core goals are to optimize documents for agent consumption, make installation and onboarding trivial, and keep the resulting wiki synchronized automatically without requiring developers to perform ongoing manual maintenance.

• Agent-oriented documentation differs from human-oriented documentation because agents retrieve fragments instead of reading a continuous narrative. OpenWiki therefore creates focused Markdown files with self-contained content, predictable headings, directory indexes, cross-links, and compact material suitable for context windows. It also includes a Quickstart page and a readable change log.

• OpenWiki applies Google's Open Knowledge Format metadata to improve filtering, search, and retrieval. Initialization configures API keys, models, and repository guidance, while generated agent instructions and GitHub Actions support continued use and updates. Early DeepSWE evaluations indicate fewer tool calls, searches, outputs, and tokens while maintaining or improving task results.