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

41–50 of 87 posts

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

#41

Post by dezgeg »

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

The best thing about monorepos is nothing ever gets versioned and packaged.

That means, a subcomponent can just make a needed change in the supercomponent as well, and test and the ship the subcomponent without excess ceremonies and releases.

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

#43

Post by WillAdams »

prepend wrote: post #4

That time was like 10 years ago. I think it’s been best practice to have docs in the repo for a long time. GitHub Pages came out in 2008.

1984 was a bit more than 10 years ago:

http://literateprogramming.com/

c.f.,

https://news.ycombinator.com/item?id=47300747

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

#44

Post by j45 »

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…

LLMs are making it more possible to maintain.

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

#46

Post by sublinear »

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…

I agree and would go one step further. The way people are now talking to LLMs to write code is the way we need them to plan and discuss in meetings with humans.

Everything regarding AI-assisted development is basically training wheels for the young people coming into the workplace.

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

#47

Post by pooploop64 »

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…

Lately I have seen a lot of things coming full circle like this in a way that always seems positive for humans as well.

Many doomers are running around saying the future is grim because everything will be made for AI agents to use rather than humans. But so far everything done to push that agenda has looked more like a big de-enshittification.

Another one is Model Context Protocol, which brings forth the cutting edge (for 1970) idea of using a standard text based interface so that separate programs can interoperate through it.

If the cost of having non-user-hostile software is to let AI bros run around thinking they invented things like stdin and documentation, I'm all for it at this point.

If any AI bros are reading this here's another idea. Web pages that use a mostly static layout and a simple structure would probably be a lot easier for AI to parse. And google, it would be really beneficial to AI agents if their web searches weren't being interfered with by clickjacking sites such as Pinterest.

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

#49

Post by xorcist »

globular-toast wrote: post #45

Wait, who didn't have the docs in the repo? Where else would it go?

Is the Git Book part of the git repo?

Is the Linux Doc Projec part of the kernel?

No. For good reasons. The only people who insists all doc must live in the same repo as the code are the ones who does not value documentation.

Note, that in both examples above there is a documentation in the main repo, but not all documentation lives there.

Post reply on HN