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

1–10 of 87 posts

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

#3

Post by jmclnx »

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.

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

#5

Post by petcat »

Out-of-band docs have always been a constant source of frustration and discrepancies. It's really difficult to keep readme.com docs updated with actual code releases because there's no hard constraint preventing one from updating without the other. It just relies on "convention".

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

#6

Post by themanmaran »

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

  ↳ docs
Using mintlify for the docs, just points to the markdown files in the docs folder. And then a line in the claude.md to always check /docs for updates after adding new code.

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

#7

Post by ssgodderidge »

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.

> Just like code should be primarily written for humans to read, all files in a repository is written primarily for humans to review

The author at least acknowledges the point of files is to be read by humans.

Also the article is talking specifically about public docs mean to be used by others, not ones you’re specifically trying to keep private

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

#8

Post by dheera »

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

Post reply on HN