Which Doc Format is Best for AI Specifications?
Skip to main content
Which Doc Format is Best for AI Specifications?
Get link
Other Apps
July 14, 2026
I have a Spec Driven Project with 674 documents incl 181 specs, 429 tasks, and 40 project docs. About 1/3 of these are an acceptance sub-project to show the root project meets fit-for-purpose requirements. I used Fable to convert these to and from AsciiDoc, Markdown, and HTML. From this, I tried to draw some conclusions about which format is better than the others for AI specifications.
TL;DR: Markdown for AI working documents, AsciiDoc for curated human-reviewed specs, HTML only as a publishing target.
Objective Metrics
Corpus Tokens (Approx)
Markdown: 594k, AsciiDoc: 598K, HTML: 661k
Worst Single-File Ratio
AsciiDoc: 1.023x, HTML: 1.26x (due to tables and code blocks)
Markup share of file content
Markdown 0.9%, AsciiDoc 1.3%, HTML 9.9% - a 10x overhead for HTML
Read/write Assessment
In terms of readability, both Markdown and AsciiDoc are good. HTML has far more tags, which add noise. One of the most common tags is
some code
however in the other formats, this is just
`some code`
When you have an average of 16 per file, this adds a lot of noise.
Usability
GitHub renders both Markdown and AsciiDoc with working links and checkboxes;<br>HTML is shown as raw source, so the review loop dies there. The first two are also easier to view while you’re editing in IntelliJ. HTML is more difficult to read and edit, and it is not as easy to view the rendered output.
If you occasionally need HTML, you don’t need HTML files: embed an island<br>with ```{=html} in Markdown (Pandoc raw-attribute syntax) or in AsciiDoc.<br>It renders where HTML is supported and drops out cleanly elsewhere. If you really need to use HTML, you can include a link to a file in that format.
Note
As these were one-for-one conversions, I didn’t use features that only exist in AsciiDoc or HTML, such as.
Markdown vs AsciiDoc
While you might choose either format for your specs, I have been following this convention to keep the authoring consistent.
Markdown
used for AI-generated content, not human-written, often not even reviewed. These are working disposable documents for the AI.
AsciiDoc
used for human-written content, reviewed and approved. These are curated specifications important enough to be preserved and maintained. They are the source of truth for the project.
HTML and DOCX
used for publishing, not for authoring.
Conclusion
The format that works best is not just the one with the fewest tokens. It is the<br>one that humans can review, tools can diff, and AI can consume without wasting<br>context on markup noise.
For this project, Markdown for disposable AI working documents, AsciiDoc for curated human-reviewed specifications, HTML/DOCX for publishing.
AI<br>Info
Get link
Other Apps
Comments
Post a Comment
Popular posts from this blog
Why You Should Tune Code Before Your Garbage Collector
June 08, 2026
Optimising your memory allocations in Java could make far more difference than your choice of Garbage Collector and may even change which is the best garbage collector. In this post I look at a simple event to response latency benchmark, MarketDataSnapshot to NewOrderSingle at 50K/s for 30 minutes using JLBH to test Chronicle-FIX. The goal is to compare a system which is doing redundant work (in this case logging each message using SLF4J), compared with not logging (Chronicle-FIX records every message internally using Chronicle Queue) and how this changes the choice of Garbage Collector For the p99 (worst 1 in 100) the choice of Garbage Collector makes a different on par with optimising how loggin is done However, for the p99.99 (worst 1 in 10,000) optimsing how the logging is done is orders of magnitude more signifciant than the choice of Garbage Collector Unoptimised Benchmark This takes the optimised benchmark and adds one SLF4J log line of just ...
Read more
Asking multiple AI to optimise the same code
July 16, 2025
As different AIs are implemented differently, they don't all provide the same answer, nor do they consistently outperform one another. The best approach is to use multiple AI and pick the one you like best. My goal here is not to declare a winner based on one example, but instead to show the variety of answers you can get with different AI. I asked each AI to Suggest how to implement this more optimally private static String formatOffset(int millis) { String sign = millis
Read more
Demystifying Java Object Sizes: Compact Headers, Compressed Oops, and Beyond
December 10, 2024
Introduction Measuring an object’s size in Java is not straightforward. The platform encourages you to consider references and abstractions rather than raw memory usage. Still, understanding how objects fit into memory can yield significant benefits, especially for high-performance, low-latency systems. Over time, the JVM...