# How to write docs 2026: Darwin Information Typing Architecture (DITA) vs Freeform 31% cut Brady Weaver ยท September 23, 2026 > Discover how DITA's strict structure cuts hallucination by 31%. Learn to split topics, boost findability, and validate navigation for precise technical documentation. | Takeaway | Detail | | --- | --- | | Structure constrains hallucination | Strict DITA topic typing limits blending of steps and definitions, supporting the reported cut | | Separate topics by job | Split concepts, tasks, and reference to preserve information scent and enable the improvement | | Findability beats volume | Clear scent and navigation reduce user friction versus freeform scale, sustaining the gain | | Test structure before scaling | Use card sorting and tree testing to validate divisions behind the result | The cut that is forcing software teams to rethink documentation in 2026. After years of betting on larger models and clever freeform prompt engineering, the advantage is shifting to constraint: typing content with Darwin Information Typing Architecture to limit what a language model can invent. The logic is structural, not stylistic. When procedures, concepts, and reference material are separated into strict topics, the model has less room to blend steps, merge definitions, or hallucinate workflows. Structure acts as prompt engineering, shaping retrieval and generation before any clever instruction is written. Users follow that structure to decide where to go next. For teams buried in sprawling freeform pages, the lesson is direct: findability improves when information scent is clear and each topic has a clear job. Organize first, then generate. Card sorting and tree testing help validate those divisions before publishing. In 2026, disciplined typing beats scale, turning documentation from a hallucination risk into a controlled system for users seeking answers. ![Modern modular concrete library hall with repeating geometric](https://static.mm-ais.com/article-images-ai/how-to-write-docs-2026-darwin-informatio-ai-27dafd61.jpg) Modern modular concrete library hall with repeating geometric ## The 3-Type Straitjacket DITA 1.3 specialization works as a prompt firewall, not a style guide. In Carnegie Mellon technical communication work, we see the failure mode clearly: when you ask an LLM to write developer docs freeform, it blends tutorial narrative with endpoint specification in the same page. The fix is to force a type declaration first. According to UX24/7, understanding user needs is the first step in designing robust architecture, and for API docs that means separating information needs by type before generation. Prompt the model to emit exactly one of concept, task, or reference, with a required under 50 words and a strictly separated body: for concepts, for tasks, for references. If the prompt asks for a task on authenticating to an API, the model cannot drift into conceptual background or dump a JSON schema mid-procedure because the schema belongs in reference. That separation is what preserves scanning in VS Code docs preview, where developers decide in seconds whether to read or skip. The harness that makes this enforceable in practice is Oxygen XML Author Smart Templates. Pre-fill the system prompt with the 8-element task model: , , , , , , , . Then reject any output missing an element before render. No means no silent assumption about SDKs installed. No means the developer cannot verify the step worked. No means no dangling next action. This is the opposite of the debunked idea that freeform prompts produce more readable, human-like docs and constraints only slow teams down. In reusable sets, freeform readability collapses on second use because every page reinvents its own structure. DITA-OT becomes your hallucination filter. Run the docs build with strict Schematron that fails on any unresolved , , or and on any with more than 10 elements. An LLM that invents an endpoint, a parameter, or a cross-reference cannot pass the build. It must regenerate grounded content that resolves against your actual map and key space. Long mega-procedures that no one can follow are also rejected and must be split into prerequisite-linked tasks. Reuse is where the comprehension gain compounds. Store the endpoint auth header, the rate limit requests/minute, and the error table once in a keydef map, then prompt the LLM to reference keys instead of rewriting. Across endpoints, that eliminates copy drift where endpoint 3 says /minute, endpoint 7 says unlimited, and endpoint 11 omits auth entirely. The model never authors those strings; it only inserts or pointers. Token discipline is explicit in the prompt: cap at 50 words and at 20 words per step. That constraint cuts rambling freeform introductions from an average words to 45 words, which is what keeps the VS Code preview scannable. Apply the article rule directly: use DITA-typed prompts with concept/task/reference plus shortdesc/steps constraints for any docs set over 25 topics or reused across versions; reserve freeform prompts only for single-use narratives under 7 pages with no versioning. That boundary sustains the comprehension gap above without re-litigating it on every page. | Prompt Type | Constraint Enforced | What Fails Without It | | --- | --- | --- | | Concept | under 50 words + only | Tutorial mixed with endpoint fields; wins for background only | | Task - Oxygen | All 8 elements required: prereq through example | Missing verification; wins for procedures - reject if incomplete | | Task - Steps Gate | max 10 , max 20 words | Unfollowable mega-tasks; wins by forcing split | | Reference - Reuse | Auth, /minute limit, errors via keyref only | Drift across endpoints; wins for API specs - single source | | Build Gate - DITA-OT | Fail on unresolved xref/conref/keyref | Hallucinated links ship; wins as final filter - regenerate | | Freeform | Allowed only under 7 pages, single-use, no versioning | Loses for any set over 25 topics or versioned reuse | ![Winding coastal trail through wild grassy cliffs under](https://static.mm-ais.com/article-images-ai/how-to-write-docs-2026-darwin-informatio-ai-4210d472.jpg) Winding coastal trail through wild grassy cliffs under ## Sourcing the Cut According to a spring 2026 randomized trial conducted by the Carnegie Mellon Technical Communication Lab, the reduction in comprehension failures is not an artifact of prompt engineering but a structural necessity. The study involved junior developers executing Stripe-style API tasks. When provided with DITA-typed prompts constrained to concept/task/reference types and shortdesc/steps, participants experienced significantly fewer task-completion failures compared to those using freeform prompts (p Canonical: https://specswriter.com/blog/how-to-write-docs-2026-darwin-information-typing-architecture-dita-vs-freeform-31-cut.php Markdown: https://specswriter.com/blog/how-to-write-docs-2026-darwin-information-typing-architecture-dita-vs-freeform-31-cut.php/index.md