Hacker News Reader

Comment by maxk42 | Hacker News Reader

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...

But we already have a folder for docs? It's called "docs". If the docs are the source code, that's fine, but that doesn't mean we have to move them into the source code folder. We already have somewhere to put them! The end goal should be for the source code folder to be in the .gitignore, same as you would with object files... but if the docs are in there, now you're stuck.

Traditionally docs were for humans as a reference.

This is not doc, this is an .md file as a src to be used by LLMs to generate code. Therefore they are src files but in english.

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.

I like how you wrote "the argument here is that maybe ad-hoc prompts is not the best way to capture that because you lose the instructions" as if you didn't begin this thread by contradicting my statement "Docs in VCS, yes." and claiming I missed the entire point of the post. It seems you've now agreed with me and yet still somehow wish to argue. I think you've missed the point of my post. You should reflect on that.

But these are NOT docs in VCS. Docs in VCS were for references for developers. The ask here is to treat them as the source for instructions.

Maybe I'm misunderstanding you, I don't know.

Of course the src directory is in VCS - it's arguably the entire point of the VCS. The entire project - including documentation - should be in VCS. Documentation is not source and should not be treated like it. But it is crucial to generating the source and always has been treated as a second-class consideration. Now that we have AI agents that can handle all the fine details of keeping the documentation up to date, I believe. We seem to be in agreement that docs should be under revision control. So the only point we seem to disagree on is where they go. My original claim was that they don't belong under the src directory. I still maintain that position. You could say that the broader point of the article was to put them under VCS and I started out with that position so there is no disagreement there. I just think it's poorly thought-out to place them under the src directory and it's even more shortsighted to place the docs in a subdirectory called 'md'. To me, these seem like the thoughts of someone who is just discovering how to craft code with the assistance of AI: They're good initial instincts, and potentially just a handful of completed projects away from a better solution, which is what people have been doing since before AI: Keep the docs separate. Keep them under revision. Keep them up to date. But documentation is not source, and even if you specify the project in intricate detail you're not going to get the same deterministic result by piping them through the same AI. And that's always been the way documentation has worked: It specifies things in as much detail as we can, but in the end someone has to translate that into source code. And typically the person writing that source code has to make decisions or trade-offs that were never specified in the docs. Now with AI agents we're able to back-port every line of reasoning into the docs and create much better and more up-to-date documentation, and that's exactly how I build with AI. But we're not able to treat the documentation as if it's a deterministic system that will generate the same outputs each time. Therefore it is meaningfully different from source code and should be treated as such. (Although it should be kept very close to the source code in a structure that is intuitive and appropriate for the project.)

In any event: If we're talking past each other or simply not understanding one another then I thank you for a respectful conversation.

I agree with this, and that's how I do it.

I don't think we are at a position to claim that documentation are the source, though to your point and the author's point as well, it serving more purpose now then what used to have.

I would say that this field is evolving really fast and we might consider and revise some practices. So I try to keep as much as open mind as possible.

So, if .md is the new "source", target LLM generated sources should be removed from VCS?

Obviously, that's the correct end result. We're just not quite there yet.

yet is extremely load-bearing here.

Like people talking about typos not substance when discussing a subject and have nothing better to add.. annoying

Reply on news.ycombinator.com