Thread

1. gwking · 1790174145 · focus · HN ↗

   The last paragraph says: > At some point your docs will outgrow a single folder, and then all bets are off. You’ll want a separate repo with its own build process...

   My question is, why is this taken as a given? Is it so hard to have docs and code live together in version control after a certain scale? If so, what is the specific problem and what is the cause?

   I ask because I've never been that satisfied with the various ways I've tried to organize projects in git. Recently I've been trying to keep the source, tests and docs together in the same tree so that changes are more localized. It seems to be helping me keep track of things, especially with coding agents so eager to make changes all over the place. I find their proclivity to repeat the same idea in multiple locations (agent instructions, docs, docstrings, help strings, comments) especially problematic.

   1. darau1 · 1790182600 · focus · HN ↗

      Weirdo checking in

      I always initialize my projects with a src, and docs, directory, for exactly this reason.

      My reasoning is that I shouldn't have to go hunting for the docs for the code, or vice versa.

      1. guipsp · 1790192363 · focus · HN ↗

         Do you have only those two dirs at the top level? If so how are you finding it? I tend to have a docs dir at the top level, along with other build stuff

         1. darau1 · 1790195018 · focus · HN ↗

            I've had no trouble so far. I'd have no problem with ephemeral build artifacts going either at the root, or in src.

            edit: I have had one pain point: devs/managers ask me why I do that, and that I stop. I refuse.

Unofficial Hacker News client; not affiliated with Y Combinator.