We are close to inventing something like deep modules [1] for markdown and a whole methodology of managing docs abstraction and layers. And I'm somewhat serious. It's hard to manage one random, interconnected bag of (spaghetti) markdown. Abstract is the new interface.
If the goal is "locality", you can't get much closer than as a comment.
As far as markdown becoming "source code for agents" under the agentic paradigm, per-directory `AGENTS.md` seems more consistent, at least visually. If agent managed markdown is going to be high-churn, I'd rather it be confined to a single file. Constraints, especially for agents, are good.
I generally put markdown in /docs. I don't uppercase filenames. Instead I make a documentation generator consume the files so I get a decent navigation in HTML/PDF builds.
We did put non-code into /src for a very long time: It was heredocs, multiline docs, etc. Actually my preference is to put texts close to code and only fallback to /docs/something.md at a conceptual level. Which is probably what the author proposes, given that he sees markdown as primary interface to code.
In terms of a documentation artifact, I love what `cargo doc` generates, but when I'm inside a source file, any plaintext solution seems so limiting.
I actually miss what I had when I was playing around in TempleOS. All text in the OS is rich (you can toggle between the markup and the standard WYSIWYG view), so comments could have formatting, colours, images (bitmap or vector, great for diagrams), hell, even (aggressively spinning) 3D models.
The thing I used most was the collapsible sections, think <details> and <summary> in HTML. Although I appreciate plain text and would hate WYSIWYG rich text in my serious source code (not to mention binary data appended to the end of the source file for images and models), I can't help but pine for those features. Being able to just draw a real diagram and being able to edit it later in seconds as opposed to making some horrid ASCII art was awesome.
I have found a lot of value in the approach the post describes. I store my markdown as GitHub issues, regardless of how I come up with a detailed feature description (usually a chat session).
Before implementation, context is always cleared to ensure that the model is working only from known context (skills, AGENT.md, etc).
A major benefit of this is that agents can look up prior prompt instructions as needed or when mentioned in the current prompt it's working on.
I still like the idea of source code as documentation and unit tests as documentation. While revising code written by an LLM to make it easier for humans to understand is now a controversial practice, I believe it's worthwhile in a lot of case.
Let’s keep the Codex session JSONL there too, why the hell not. And the debug build logs, since they’re easily greppable text useful for diagnosing recurring problems. And logs/reports from every test run - a ton of useful info there, lets you track regressions over time; would be a shame to throw it away. We could also store screenshots of every app run to have a LLM-compatible historical record of how each component changed visually. And the token provider billing documents, since we’re gonna have a lot of those once we’ll start maintaining all that.
1. he is saying md/english is the new source code..
2. yes - it is different that is geared towards english and very well supported by LLMs that is why it is being used in memory and instructions
3. llms are deterministic enough to translate adequately described specs into working system, the idea here is reason in md for core flow etc, and then verify with test cases
this not perfect but he is describing a real trend, so listen with open mind.
src/md doesn’t seem all that different from docs. Maybe it changes how people search the filesystem, though?
If you split code up into multiple packages, moving the docs closer to the code might make sense. The docs for package foo could be in packages/foo/docs.
We are close to inventing something like deep modules [1] for markdown and a whole methodology of managing docs abstraction and layers. And I'm somewhat serious. It's hard to manage one random, interconnected bag of (spaghetti) markdown. Abstract is the new interface.
1. https://softengbook.org/articles/deep-modules
My favourite projects typically have documentation in comments.
One example is SpiderMonkey, which uses these beautiful, long expository comments explaining not only what, but why design choices have been made. https://searchfox.org/firefox-main/source/js/public/RootingA...
If the goal is "locality", you can't get much closer than as a comment.
As far as markdown becoming "source code for agents" under the agentic paradigm, per-directory `AGENTS.md` seems more consistent, at least visually. If agent managed markdown is going to be high-churn, I'd rather it be confined to a single file. Constraints, especially for agents, are good.
I generally put markdown in /docs. I don't uppercase filenames. Instead I make a documentation generator consume the files so I get a decent navigation in HTML/PDF builds.
We did put non-code into /src for a very long time: It was heredocs, multiline docs, etc. Actually my preference is to put texts close to code and only fallback to /docs/something.md at a conceptual level. Which is probably what the author proposes, given that he sees markdown as primary interface to code.
In terms of a documentation artifact, I love what `cargo doc` generates, but when I'm inside a source file, any plaintext solution seems so limiting.
I actually miss what I had when I was playing around in TempleOS. All text in the OS is rich (you can toggle between the markup and the standard WYSIWYG view), so comments could have formatting, colours, images (bitmap or vector, great for diagrams), hell, even (aggressively spinning) 3D models.
The thing I used most was the collapsible sections, think <details> and <summary> in HTML. Although I appreciate plain text and would hate WYSIWYG rich text in my serious source code (not to mention binary data appended to the end of the source file for images and models), I can't help but pine for those features. Being able to just draw a real diagram and being able to edit it later in seconds as opposed to making some horrid ASCII art was awesome.
I wrote something similar a few months ago [1], though admittedly I haven't been following my own advice terribly well.
The interesting part of any program source is what it took to make that program. I view AI-generated code in the same category that I see a binary.
[1] https://blog.tombert.com/Posts/Technical/2026/04-April/Stop-...
Developer documentation in /src, yes. Anything else, no way.
IME developers have low tolerance for interrupting flow to track down the docu that is aimed at them, so keep it near and obvious.
I have found a lot of value in the approach the post describes. I store my markdown as GitHub issues, regardless of how I come up with a detailed feature description (usually a chat session).
Before implementation, context is always cleared to ensure that the model is working only from known context (skills, AGENT.md, etc).
A major benefit of this is that agents can look up prior prompt instructions as needed or when mentioned in the current prompt it's working on.
I recently described my workflow here https://jaisenmathai.com/articles/sojourn-for-ios-was-45-one...
Docs in VCS, yes. Docs in /src, no.
You missed the entire point of the post..the author is arguing docs in md are the src...
I still like the idea of source code as documentation and unit tests as documentation. While revising code written by an LLM to make it easier for humans to understand is now a controversial practice, I believe it's worthwhile in a lot of case.
Let’s keep the Codex session JSONL there too, why the hell not. And the debug build logs, since they’re easily greppable text useful for diagnosing recurring problems. And logs/reports from every test run - a ton of useful info there, lets you track regressions over time; would be a shame to throw it away. We could also store screenshots of every app run to have a LLM-compatible historical record of how each component changed visually. And the token provider billing documents, since we’re gonna have a lot of those once we’ll start maintaining all that.
So
1. he's describing a manual version of Spec-Kit / OpenSpec / BMAD?
2. Thinks Markdown is... somehow different from normal text or other markup languages?
3. Doesn't seem to understand that LLMs are not deterministic?
1. he is saying md/english is the new source code.. 2. yes - it is different that is geared towards english and very well supported by LLMs that is why it is being used in memory and instructions 3. llms are deterministic enough to translate adequately described specs into working system, the idea here is reason in md for core flow etc, and then verify with test cases
this not perfect but he is describing a real trend, so listen with open mind.
This sounds a lot like a low tech version of Delta from Zed. All your agent transcripts live in the same place as code.
src/md doesn’t seem all that different from docs. Maybe it changes how people search the filesystem, though?
If you split code up into multiple packages, moving the docs closer to the code might make sense. The docs for package foo could be in packages/foo/docs.