HORNEKS ANS

AI works best when the documentation is built for AI

by · Published · Updated

One thing has become very clear while working with Codex and other AI coding assistants:

The quality of the generated code depends just as much on the reference material as on the prompt itself.

For years, the ACF Plugin manual has existed as a traditional website. That works well for human readers, but modern AI agents don’t really “browse” documentation the same way we do. HTML pages contain navigation menus, headers, footers, CSS, JavaScript and lots of surrounding noise that isn’t part of the language specification.

So I decided to build something different.

The entire ACF reference is now available as a Markdown-based manual designed specifically for AI-assisted development.

Instead of asking an AI to understand a complete website, it can now work directly with clean Markdown documents containing only the information that matters.

The package includes:

  • A Markdown index with every document, its URL, title and a short description.
  • One Markdown file for every reference page.
  • An AGENT.md file describing how an AI assistant should work with the documentation.
  • A ZIP archive containing the complete manual, ready to unpack directly into your project workspace.

This means that if you’re using Codex or another coding agent, you can simply place the manual beside your project. The AI can then reference the complete ACF language locally while generating code, instead of repeatedly searching through HTML pages.

In practice, this gives several advantages:

• Less context is wasted on HTML and website layout.

• The AI spends more of its context window on the actual language reference.

• Navigation between related topics becomes faster through the generated index.

• Offline development becomes possible because the complete manual is available locally.

• The AI can reason across the entire language reference instead of isolated pages.

The interesting part is that this approach is not limited to ACF.

As developers, we should start thinking about documentation in two different ways:

  • Documentation written for humans.
  • Documentation structured for AI agents.

The two audiences have different needs. Humans appreciate attractive websites and navigation. AI systems perform better when they receive clean, structured, semantically organized text.

I believe this will become increasingly important as AI-assisted development becomes part of everyday programming.

If you’re experimenting with Codex, ChatGPT, Claude or other AI coding assistants for FileMaker development, I’d be interested to hear your experiences. Have you started adapting your documentation for AI, or are you still relying on traditional web manuals?

The new AI-friendly ACF documentation is available here:

Markdown index: https://horneks.no/manuals/ACFmd/index.md

AGENT.md: https://horneks.no/manuals/ACFmd/AGENT.md

Complete Markdown manual (ZIP): https://horneks.no/manuals/ACFmd/ACF-Markdown-Manual.zip

I’m looking forward to seeing what the FileMaker community builds when AI has direct access to a clean, structured ACF reference.

You may also like...