<h1>Engineering Documentation Needs to Evolve for the AI Era</h1>
<p>As AI coding assistants become part of our daily workflow, I’ve been thinking about a question:</p>
<p><strong>Are our documentation practices keeping up?</strong></p>
<p>Most engineering knowledge today is fragmented across README files, internal wikis, architecture documents, Slack conversations, ADRs, and—too often—people’s memories.</p>
<p>This creates familiar problems:</p>
<ul>
<li>New engineers spend too much time searching for information.</li>
<li>Architectural decisions become difficult to trace.</li>
<li>Documentation quickly falls out of sync with the code.</li>
<li>AI coding assistants receive incomplete or inconsistent context.</li>
</ul>
<p>Instead of treating documentation as static pages, I think we should treat it as a structured knowledge system.</p>
<p>A workflow I’ve been exploring combines three complementary projects:</p>
<h3>📝 Obsidian — Authoring</h3>
<p>Developers create and maintain documentation locally using Markdown. Obsidian makes it easy to organize notes, link related concepts, and evolve documentation alongside the codebase.</p>
<h3>🧩 Open Knowledge Format (OKF) — Structure</h3>
<p>OKF provides a standardized way to represent organizational knowledge using structured Markdown and metadata. The goal is to make documentation understandable by both humans and AI systems while remaining portable across tools.</p>
<h3>📚 OpenWiki — Publishing</h3>
<p>OpenWiki transforms that structured knowledge into a centralized engineering wiki that can stay synchronized with the repository and become a reliable source of truth for both developers and AI coding agents.</p>
<h2>The Workflow</h2>
<p>Source Code</p>
<p>⬇️</p>
<p>Obsidian (Authoring)</p>
<p>⬇️</p>
<p>Open Knowledge Format (Standardized Knowledge)</p>
<p>⬇️</p>
<p>OpenWiki (Central Knowledge Portal)</p>
<p>⬇️</p>
<p>Developers + AI Coding Agents</p>
<p>The part I find most interesting isn’t any individual tool—it’s the separation of responsibilities:</p>
<ul>
<li>Authoring</li>
<li>Knowledge standardization</li>
<li>Publishing</li>
<li>AI consumption</li>
</ul>
<p>That architecture makes the documentation workflow more scalable, maintainable, and adaptable as tools evolve.</p>
<p>I’m curious how other engineering teams are approaching this challenge.</p>
<ul>
<li>Are you keeping documentation AI-ready?</li>
<li>Have you experimented with structured knowledge formats like OKF?</li>
<li>Do you think documentation should become another artifact generated and maintained alongside the code?</li>
</ul>
<p>I’d love to hear your thoughts and learn what workflows have worked well for your teams.</p>


MHD SUBHI AL WATTAR

Engineering documentation practices are struggling to keep up with AI-assisted development workflows. Most knowledge is fragmented across READMEs, wikis, ADRs, and Slack. A proposed workflow combines Obsidian for authoring, Open Knowledge Format (OKF) for structured standardization, and OpenWiki for publishing — creating a pipeline that serves both developers and AI coding agents. The key insight is separating documentation responsibilities into authoring, standardization, publishing, and AI consumption to make the system more scalable and maintainable.