Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

It's time to move your docs in the repo

dein.fr

Post reply on HN
Print view View original

31–40 of 87 posts

Re: It's time to move your docs in the repo

#31

Post by basilikum »

susam wrote: post #25

It is a bit weird to see LLMs suddenly being presented as the reason to follow what are basically long standing best practices. 'You must write docs. Docs must be in your repo. You must write tests. You must document your architecture. Etc. Etc.' These were all best practices before LLMs existed and they remain so even now. I have been writing extensive documentation for all my software for something like twenty year…

> The reason is simply that tests and documentation are useful to other humans working on the codebase.

Including future you

Re: It's time to move your docs in the repo

#32

Post by sigbottle »

There's a lot of things that we mean when we say 'docs'.

The great talk "No Vibes Allowed" put me to the far end of the other extreme - persistent long term state on disk is bad. Always force agents to rebuild, aggressively sub agent or use tools to compress context. The code should be self documenting as much as possible and structured in a way such that it's easy to grep through it. No inline docs trying to describe the structure of the tree (okay, maybe like, 3 at most).

I don't have the time to build such an elaborate testing harness as they do though. So instead I check in a markdown jungle in ROOT/docs/* . And garbage collect them aggressively. Most of these are not "look for where the code is", they are plans of varying length, ADRs, bug reports, etc. and they all can and *will" get GC'ed.

I still use persistent docs but they're very spare and often completely contractual. "Yes, I can enumerate the exact 97 cases I need to support, and we are tracking each of these in a markdown doc". That is fine IMO. Not "here let me explain what this code does". Or even ADRs - I love ADRs, but at least for my use case, I've thrown out the project and rewritten from scratch when too many of them got cluttered up... Lol.

I'm also re-implementing an open source project (with the intent of genuinely making it better as a daily user, licensed under the same license, and not just clean rooming it), which makes markdown spam less appealing to me. I kind of wish there was yet another git wrapper like jujutsu which easily layered and kept commits unified on the same branch but had multi-level purposes like this. Persistent History for some things is not needed, but git as a wrapper for everything is so convenient. Maybe I just submodule the notes....

Note: my approach isn't the best, heck, 1 month ago OpenAI wrote an article on harness engineering where they had many parallel agents working, including some which aggressively garbage collected. They garbage collected in the sense that yes, prolific docs point agents to places XYZ, but if something goes out of date, sync the docs. Again, That works if you have a huge compute basin. But for my use cases, my approach is how I combatted markdown spam.

Re: It's time to move your docs in the repo

#33

Post by xixixao »

We have been on this path at work. But I challenge everyone to consider what you lose with MD vs Confluence (et al). It is NOT easier to author, comment on, label, view history of, move without breaking links, etc. markdown docs vs Confluence. If I am the sole author plus my AI and the scope is narrow (a library), I go for MD. But for a big org, process docs, fast iteration… I’m not convinced, until someone builds equally powerful editing UI on top of MD files.

Re: It's time to move your docs in the repo

#34

Post by rikroots »

jmclnx wrote: post #3

Sounds like they are saying use a repo like git for your documents to help AI read/"understand" your docs. Is that correct ? I am all for using a source control system for your documents, I usually use RCS. But give AI access to your docs, no thanks. If I upload any of my docs to a public server (very rarely happens), they are compressed and encrypted to make sure only I and a few people can view them.

For me it's a case of, I have to expose my canvas library documentation for the training data bots to find and (hopefully) include in the LLM training data because it's the only way I'll ever get LLMs to:

A) accept that my library exists, and has its uses (it's a tough world out there for canvas-focussed JS libraries that aren't Fabric.js, Konva.js or Pixi.js)

B) learn how to write code using my library in the best way possible (because the vibes ain't going away, so may as well teach the Agents how to do the work correctly)

Plus, writing the documentation[1] for a library I've been developing for over 10 years has turned into a useful brain-dumping activity to help justify all the decisions I've made along the way (such as my approach to the scene graph). I'm not going to be here forever, so might as well document as much as I can remember now.

[1] - https://scrawl-v8.rikweb.org.uk/docs/reference/index.html

Re: It's time to move your docs in the repo

#35

Post by [deleted] »

susam wrote: post #25

It is a bit weird to see LLMs suddenly being presented as the reason to follow what are basically long standing best practices. 'You must write docs. Docs must be in your repo. You must write tests. You must document your architecture. Etc. Etc.' These were all best practices before LLMs existed and they remain so even now. I have been writing extensive documentation for all my software for something like twenty year…

[deleted]

Re: It's time to move your docs in the repo

#36

Post by fixxation92 »

dheera wrote: post #8
themanmaran wrote: post #6

We just did this the other week and it's such a great setup using AI. Monorepos in general are better for coding agents since it's a single location to search. But now we have the ability to say "Add xyz optional param to our API" and claude adds the code + updates the documentation. I was also able to quickly ask "look at our API and our docs, find anything out of date". Our set up is: packages/ ↳ server ↳ app ↳ doc…

The one thing I hate about monorepos is nothing ever gets versioned, packaged, and shipped. Polyrepos are workable, the way to do it is to actually version, ship, and document every subcomponent. When I mean ship, I really mean ship, as in a .deb package or python wheel with a version number, not a commit hash. AI can work with this as well, as long as it has access to the docs (which can also be AI-generated).

I've got about ~15 repos for a project and I just start Claude Code in the parent directory of all of them, so it has clear visibility everything and cross-reference whatever it needs.... super handy.

Re: It's time to move your docs in the repo

#37

Post by cindyllm »

basilikum wrote: post #31
susam wrote: post #25

It is a bit weird to see LLMs suddenly being presented as the reason to follow what are basically long standing best practices. 'You must write docs. Docs must be in your repo. You must write tests. You must document your architecture. Etc. Etc.' These were all best practices before LLMs existed and they remain so even now. I have been writing extensive documentation for all my software for something like twenty year…

> The reason is simply that tests and documentation are useful to other humans working on the codebase. Including future you

[dead]

Re: It's time to move your docs in the repo

#38

Post by ronsor »

susam wrote: post #25

It is a bit weird to see LLMs suddenly being presented as the reason to follow what are basically long standing best practices. 'You must write docs. Docs must be in your repo. You must write tests. You must document your architecture. Etc. Etc.' These were all best practices before LLMs existed and they remain so even now. I have been writing extensive documentation for all my software for something like twenty year…

AI means that you cannot defer software design until you've written half code; you cannot defer documentation to random notes at the end.

It has the effect of finally forcing people to think about the software they're making, assuming they care about quality. If they didn't, then it's not practically different from an insecure low-code app or something copy-pasted from 15 year old StackOverflow answers.

Re: It's time to move your docs in the repo

#39

Post by 01HNNWZ0MV43FF »

sigbottle wrote: post #32

There's a lot of things that we mean when we say 'docs'. The great talk "No Vibes Allowed" put me to the far end of the other extreme - persistent long term state on disk is bad . Always force agents to rebuild, aggressively sub agent or use tools to compress context. The code should be self documenting as much as possible and structured in a way such that it's easy to grep through it. No inline docs trying to descri…

ADR = "Architecture Decision Record" https://github.com/joelparkerhenderson/architecture-decision...

Re: It's time to move your docs in the repo

#40

Post by forrestthewoods »

susam wrote: post #25

It is a bit weird to see LLMs suddenly being presented as the reason to follow what are basically long standing best practices. 'You must write docs. Docs must be in your repo. You must write tests. You must document your architecture. Etc. Etc.' These were all best practices before LLMs existed and they remain so even now. I have been writing extensive documentation for all my software for something like twenty year…

> It is a bit weird to see LLMs suddenly being presented as the reason to follow what are basically long standing best practices.

About 95% of the work needed to make LLMs happy is just general purpose better engineering. Units tests? Integration tests? CI? API documentation? Good example? All great for humans too!

I consider this largely a good thing. It would be much worse if the changes needed for Happy LLMs were completely different than what you want for Happy Humans! Even worse would be if they were mutually exclusive.

It's a win. I'll take it.

Post reply on HN