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