Which Doc Format is Best for AI Specifications?
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 <code> some code </c...