Comment by maxk42
1 hour ago
No, this is not a source file to be used to generate code. It's a spec to be used to build the code to - same as any other document. Aside from the fact that docs can be in any format - not merely .md - they do not belong in `src/`. Why? Well for one, many of my projects have multiple `src/` directories because they involve multiple binaries. But the documentation used to generate that source is in the project, not the `src/` directory of one of its binaries. I'm building a video streaming site that uses one server for the SFU, one server for the web interface, one server for the websocket connections, as well as STUN and TURN servers. None of the project works unless all these separate binaries are working together and communicating. Which `src/` directory should I place these markdown files in? What about the `.sql` files I use to spec out the database schema before passing it off to the LLM? What about the mermaid files, code snippets, `.txt` files, and data files used as part of the documentation project? Should they all go in `sfu/src/md/`? No. The project is one whole with multiple `src/` directories and they all require their own documentation. Beyond that they need access to each other's documentation so that when the agent is working on one part of the system it can still be aware of how the other pieces operate. Documentation should absolutely be under version control, but placing it in the `src/` directory is plainly the wrong call. And there is more documentation than just markdown. This was a shower thought that wasn't completely fleshed-out (and the article admits it wasn't) and never should've made it to the front page of HN.
This is an experimental thought. If people are vibe coding apps without looking at code, the argument here is that maybe ad-hoc prompts is not the best way to capture that because you lose the instructions. So the proposal, why not have those instructions saved as markdown files at least we have a reference in English.
We don't look at binaries, we don't look at assembly, we work with high level languages. The specs were for developers to translate to programming primitives, but if the translation is largely automated, then the specs will become the code and we will need better ways to manage those, and I think the IDEs are gradually trending that way, look at all the most recent agentic dev tools, it surely follows that trend.
With respect to not having this piece on HN. If the author is seeing many organizations doing this practice, then why he would not share that empirical observation? is it only because it is against your pure world and abstractions? Just the recent leak for the Muse agent shows that most of the system behaviour is written in markdown.
Whether you like it or not, technology never care about purest and idealist, it evolve under pressure of deliveries and pragmatic choices, and if there is such a pressure, which the author claims to be, then HN is the medium to share it.