Commenters debate directory organization and markdown viability
5 Sep 21 12:24 PM · 6d ago · 1 post · 9 comments · 2 sources · development 5 of 5
dlisboa argues the proposed /src/md flat directory structure mirrors the mistake of grouping code by language rather than by module. zetashift and toastal express skepticism about markdown as a formal specification vehicle, noting that typed documentation systems and DSLs offer more predictable guarantees.
“Documentation should live close to what it documents.”
dlisboaBrady Olano Montana State University professor, AI consultant
The whole story postscomments the bright band is this development · numbered dots are the others · click one to jump
What people said 24 voices · best of 29 · verbatim
-
> Markdown is becoming source code, not documentation :c
-
Personally, I build a loosely compiled / linted DSL to handle spec.It's a SEXP language but could just as easily be markdown. It'd probably be better if it was - I spend a lot of tokens matching parentheses.Compared to markdown - I lose some human readability but gain a lot in workflow.For me - it turns the sort of "free form jazz code odyssey"…
-
H
Markdown in /src L: https:// htmx.org/essays/markdown-in-sr c/ C: https:// news.ycombinator.com/item?id=4 9794478 posted on 2026.09.21 at 18:47:54 (c=0, p=6)
-
I don't know how this is actually supposed to work. I do write detailed initial prompts, and I often try to capture those (usually in the commit message), but for anything nontrivial there follows several back and forth rounds where I'm telling it "actually, rip out the Foo and try just augmenting Bar" or "add some tests for condition X (and fix…
-
If we go that route, can we have rich syntax highlighting, "go to definition"/"show usage sites", debuggers etc for the markdown docs as well? :)But I don't really like the "LLMs as compiler" metaphor. If you followed that logic to the end, you'd have to "rebuild" your entire project from the spec every time the spec changes. Not just would the…
-
Really hard pass on this here, but I can definitely see why people want this, it sits right around the "tickets/discussion should be colocated with code" discussions. Elixir has `exdoc`, Rust has `rustdoc` and Unison has `{{ fancy doc comments}}`, there are also a quite a lot of notebook-style programming environments. I feel like all of those…
-
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…
-
In some projects, I will create a root folder `docs/`. I will then number files `YYYY-MM-DD-title.md`, or `NNN-title.md` starting at `000` and counting up. I strictly keep only human-authored documents in this folder. I will do things like spec out interfaces and tests and invariants by hand, and then write automated checks to ensure that the…
-
I think I'm with the majority of commenters here in thinking this would just wind up being clutter. Markdown might now generate code, but it isn't user facing and doesn't get shipped (I don't want to install a library and have a tonne of prompt text unnecessarily downloaded). I also don't really want to be on the hook for maintaining my co-workers…
-
I’m not getting it either. Type systems are deterministic & are trying to encode invariants in a predictable manner—2 features LLM outputs don’t have. …& this is already frustrating enough that such a bad format for documentation/technical writing, Markdown, is being plopped all over the place; it’s as ergonomic & feature rich as JavaScript’s type…
-
You've seen test-rot, specification rot, and documentation rot; we now introduce; prompt rot!Cluttering the repo with out-dated, very wordy and quickly aging prompts will just confuse any agent tasked with looking at the repo in the future. Keeping context windows down is a real limitation to good LLM output, and this workflow may work completely…
-
I think a possible consequence of the proposed model would be that every time (or every few times) you uncover new things like this, you would have to (manually) incorporate them back into the initial document and restart the session. I would complement with LLM CI reviews that judge whether the final implementation honors what is captured in the…
-
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…
-
I disagree with that. Either way, we don't categorize source code by file type.
-
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]
-
In my projects /docs is human authored and for humans /ai-docs/ is LLM-generated and specifically formatted to be LLM-readable. The two shall not cross.
-
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…
-
The Algernon webserver can serve `.prompt` files directly (deterministic and cached results), using local LLMs.
-
Agree with markdown being important. I still see it as intent, processing it results in a new commit not part, hence I would not put it in src.My conclusion is, that i want neat markdown. Hence it needs to be linted/formatted.Developed a linter/formatter https://mdsmith.dev to specifically do that. Includes tooling for progressive disclosure, etc.
-
Maven's `src/main/java` is one example to the contrary, though you're free to argue it's a bad idea.
-
I wonder if instead of checking the prompts into the repo as files, a better idea would be to store them inside the commit messages.If prompts are specifications for a change of the system's behavior, then it seems natural to manage them as changes and not as resources.This would also keep them in the right "historical context" of the repo and…
-
I think these are different things. The source code, it’s tests, it’s documentation, it’s data. They are different perspectives to approach a given body of work while together building an overall understanding. It doesn’t matter at all where the files live but when you approach the work from that perspective you know how to find it, and I don’t…
-
Markdown is non deterministic when it comes to piping it through an LLM. Sure the prompt intent is the same, but it doesn't guarantee the same output.I would much rather have significantly more detailed comments inline with code to describe the intention at any given step than just a high level markdown file. We already have PDRs and markdown…
-
Couldn't agree more. Rot is rot. People hate reading giant verbose AI generated PRs. Imagine mandating your codebase requires people now also read AI generated markdown files to compare the AI intent with the AI outcome. What a laugh and this is the guy giving out CS degrees and opposing React.
All 5 developments of Montana State prof proposes /src/md directory for… →
Hacker NewsLobstersMastodon