I see two traps here that I largely blame, curious if there are more. First is that documentation is only worth it if you are keeping everything surrounding it

I see two traps here that I largely blame, curious if there are more. First is that documentation is only worth it if you are keeping everything surrounding it stable. Software has been changing a ton in the past few decades such that a lot of documentation from last year is irrelevant. I /think/ this is slowing down, but I can't say for sure. Examples for this are many. Python 2->3, Web frameworks 10 years ago (this one has legit gotten better), general systems management and deployment. Second is that it was easy to get burned by documentation that was really more of a promise of things to come. By that I mean you think you are going to buckle down, research the right way, and make progress. Only to find out that all of the time you just dumped into the "right way" doesn't actually work today. It may work next week, but if you want to do something today, you have to do it the way they did it before. Which is a ton of warnings about how you will need to be prepared to upgrade, at this point. Examples of this, for me personally, have been trying to use XHTML back in the day, WSDL promises, and now OpenAPI.