Markdown in /src (htmx.org)

Carson Gross proposes an innovative shift in software development by advocating for Markdown to be treated as source code rather than mere documentation. By storing Markdown files in the source directory alongside generated code, he argues that Markdowns should encapsulate the architectural and design decisions behind the code, enhancing accessibility for both human developers and AI agents. This approach seeks to improve the “locality” of documentation, eliminating the disconnect often created by storing specifications in separate tools like wikis or project management software. This transition is significant for the AI/ML community as it redefines how software intent is captured and understood, moving away from ephemeral prompting sessions that can obscure the reasoning behind generated code. Instead, by establishing Markdown as a core component of the development process, teams can ensure the intent and specifications of their software systems are easily traceable and comprehensible, thus facilitating better communication between humans and AI-driven tools. Gross emphasizes the need for structured collaboration between Markdown and derived code while maintaining a focus on human authorship to curate these documents effectively.