Hacker News Reader

Comment by prepend | Hacker News Reader

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.

The best time to plant a tree was 30 years ago. The second best time is now.

It's a good saying but the literal meaning is not entirely correct anymore. Climate change has changed the math on tree planting in a few ways. For example tree planting in your area today may backfire vs 30 years ago: https://www.scientificamerican.com/article/forest-preservati...

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.

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.

Isn’t the second best time 29 years and 364 days?

I get the principle but it seems like there are many other times to plant than now.

1984 was a bit more than 10 years ago:

http://literateprogramming.com/

c.f.,

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

if you aren't using github because you're at a big company with its own git UIs, you still have to make the case that your company needs this thing.

I'm sure there's a ton of places where its been hard to do that in the past in a way where the docs are easily accessible where people are looking

but with agents, even just pulling the code package to get the docs is fine

I use Jekyll and other builders independent of GitHub. So even weird companies with other git repos can still autogenerate docs.

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

I disagree. Sometimes it’s useful to point out dumb things. As long as it’s not cruel. I think being efficient in speech is helpful and no need to be constructive with silly or damaging comments.

I don’t think this is a case of just finding something late, it’s finding something decades after it’s very common. And strange that the author didn’t reference this old practice.

I don’t think my comment is any snarkier than yours.

My intent wasn’t snark, but more incredulity at how the post was written and how it states some very old, commonly accepted best practice was novel or finally time to use.

I’d make a similar comment if someone posted that now is the time to use object oriented programming. And I wouldn’t do so in a snarky way.

Python Sphinx as well.

Reply on news.ycombinator.com