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

71–80 of 87 posts

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

#71

Post by 9rx »

bryanlarsen wrote: post #69
9rx wrote: post #54

Earlier quoted context omitted.

The best time to move your docs to your repo was 30 years ago. But now that they are written by LLMs, tomorrow's LLM will be able to write an even better doc than today's LLM. Nothing is gained in caching them now.

If that's true, you've got the wrong stuff in your docs. Capture the why's. LLM's can synthesize the what's and how's.

Unless you're doing something wrong, the "why" is already captured in your test suite/type system. While you can fairly call that documentation (that is the point of it!), the linked story is about natural language documentation. That can be extracted from your tests/types at will, and as models keep getting better extracting later will be better than extracting now.

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

#72

Post by palmotea »

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 also a bit funny that these considerations did not seem very common when the beneficiaries were fellow human collaborators, but are now being portrayed as very important once LLMs are involved. I'd argue that fellow humans and your future self deserved these considerations even more in the first place.

The reason might have been a cultural regression. At least with documentation, it seems to have been much better and a bigger priority a couple decades ago.

At the start of my career, teams produced documents as a part of their work, and there were even technical writers on staff. Then agile hit, the writers were laid off, much of what little documentation that was created was kept in various work-tracking systems and wikis that were periodically replaced, often with little to no migration.

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

#73

Post by giorgioz »

satvikpendem wrote: post #15
giorgioz wrote: post #12

Earlier quoted context omitted.

that's true. Take care because in the YCombinator there is "Don't be snarky". Ask yourself how you could have provided the same useful insight without being snarky: https://news.ycombinator.com/newsguidelines.html

I don't see anything snarky about their comment. That rule is for cases where people are overly sarcastic and argumentative, not for comments like the above.

snarky critical or mocking in an indirect or sarcastic way.

I think the constructive information is mentioning Github Pages were built on .md file and they have existed for 10 years. That's true and useful.

The snarky part happens when phrasing the sentence "Ah you guys only doing this now? It has existed for 10 years" that part is talking about something constructive but it's also trying to diminish the discovery of someone else. We all find and develop at different times. In general is better to be constructive and happy someone else is joining you in using something than underline how it was already done in some way by you or others and this new discovery is irrelevant. Everything that exists already existed (in some other shape or smaller parts).

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

#74

Post by GeoSys »

For open source, this has been the practice for many projects. The docs is often in README.md or in a separate folder "docs". For larger projects, there could be a separate repo from where a docs site is built.

However, in corporations, docs are often in Confluence or MS Sharepoint, separate from the code. Tech specs often require comments, discussion, or estimate/budget approvals from non-tech staff. Hence, some corporate AI coding tools can refer to docs in such corporate sites. That doesn't work too well yet, IMHO ... time will show.

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

#75

Post by codethief »

> Answer to objections

> Non-engineers usually don't have repo access. [Answer:] (1) You can deploy your docs on an internal-only website. (2) There is clear trend with non-engineer code access (which poses some interesting security challenges).

Regarding (2): If, on the other hand, you have your agent use MCP to query, e.g., Confluence, anyone with access to Confluence could in theory do a prompt injection and possibly get access to your repo.

At least doc changes in the repo will undergo code review.

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

#76

Post by AlexeyBelov »

theletterf wrote: post #28

There’s an irresistible, almost demoralizing irony in the fact that developers are discovering docs and accessibility only now due to AI. They needed docs and didn’t know it until they had at their disposal an ersatz user in the form of an LLM that asked for context. https://passo.uno/skills-are-docs/

At $job and $previousJob we (the devs) were never given time to properly keep the documentation up-to-date. It didn't matter that people were asking the same questions and discovering the same things again and again.

Now, at $job, there is a top-down directive for quickly documenting every part of every important workflow and every idiosyncrasy of our products.

So, developers knew that all along.

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

#77

Post by lelanthran »

ronsor wrote: post #38
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.

> 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,

Ah, and all this time I was reliably assured that waterfall, design-upfront, was a broken process...

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

#78

Post by bryanlarsen »

9rx wrote: post #71
bryanlarsen wrote: post #69

Earlier quoted context omitted.

If that's true, you've got the wrong stuff in your docs. Capture the why's. LLM's can synthesize the what's and how's.

Unless you're doing something wrong, the "why" is already captured in your test suite/type system. While you can fairly call that documentation (that is the point of it!), the linked story is about natural language documentation. That can be extracted from your tests/types at will, and as models keep getting better extracting later will be better than extracting now.

That's great, if you only want to see the trees. Views of the forest are important too.

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

#79

Post by hex-m »

forrestthewoods wrote: post #40
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…

Reminds me of the "semantic web". Making content machine-readable has positive side effects. (clear structure, reduced ambiguity, separation of data and presentation)

It's another example where the reason for better engineering is to make machines (search engines) happy.

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

#80

Post by 9rx »

bryanlarsen wrote: post #78
9rx wrote: post #71

Earlier quoted context omitted.

Unless you're doing something wrong, the "why" is already captured in your test suite/type system. While you can fairly call that documentation (that is the point of it!), the linked story is about natural language documentation. That can be extracted from your tests/types at will, and as models keep getting better extracting later will be better than extracting now.

That's great, if you only want to see the trees. Views of the forest are important too.

Don't get me wrong, I'm sure future historians appreciate when you document that John, when trying to determine how to figure out how to exchange data in your application, took a drink from his Diet Coke that happened to have a fly in it and as he spit it out eureka struck: Data can be pushed to the client like a firehose.

But let's be real, that's never going to happen. No matter what format you give someone, they're not going to write that kind of thing down. They will, however, encode why a firehose approach is necessary to both document it for future readers and to ensure that the program doesn't accidentally (or possibly on purpose by an eager junior dev) move to, say, a pull method that won't meet the business/technical requirements. Which LLMs can extract a natural language version from.

And, really, that's the only "why" that actually matters to other developers trying to get their job done. The forest, while perhaps full of fun stories that I am sure are entertaining to read, doesn't matter all that much.

Post reply on HN