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