Rendered at 11:52:02 GMT+0000 (Coordinated Universal Time) with Cloudflare Workers.
skybrian 32 minutes ago [-]
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.
Naru41 1 hours ago [-]
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.
ktpsns 6 hours ago [-]
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.
euroderf 2 hours ago [-]
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.
tancop 5 hours ago [-]
This sounds a lot like a low tech version of Delta from Zed. All your agent transcripts live in the same place as code.
throwuxiytayq 5 hours ago [-]
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.
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 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.
IME developers have low tolerance for interrupting flow to track down the docu that is aimed at them, so keep it near and obvious.