The JavaScript ecosystem seems uniquely poor at this docs inconsistency stuff. It’s almost like someone lowered the bar one day, and then everyone else learned from that low bar and all think that their behaviour makes any sense whatsoever.
I’ve been tinkering with a lot of mainstream JS frameworks and they pretty much all have their version of this problem.
Next has their new App Directory stuff going on with its own beta docs site. It’s been a few weeks since I looked, so I can’t remember the specifics, but the messaging on the new and old docs sites was not good enough for me to immediately grok what was going on. It also made Googling near impossible.
We got our long-awaited next major version of Nuxt not long ago, too. They seemingly decided that they could just change domains, put a little banner up on the old site, and make the problem go away. Again, makes Googling incredibly hard. I found myself having to remember the design and domain of the old and new sites to know if I’d accidentally stumbled on old documentation. I really want to make Nuxt work for me, but this docs experience left a bad taste in my mouth, a very specific “pre-production” taste, which is really unfortunate given Nuxt’s cadence with v3 stability.
React was about as bad as Next. I found myself bouncing between the stable and beta docs consistently. All the messaging around the stability and supported use cases for Suspense is just…way too impenetrable. I’m a seasoned web application developer. I’m confident that the majority of this isn’t a “me” problem.
The only docs experience I’ve had that comes close to addressing the issue appropriately is the Vue documentation. There’s a nice big switch at the top that switches the docs from favouring the old-school vs composition APIs.
Of course, the underlying problem is React and Vue so solidly keeping their foot in both camps. This is just an outcome of that.
I try my absolute hardest to enter the JS ecosystem with the most open of minds, and there are plenty of people working in this space that are certainly much smarter than me. I just get the impression that there are too many people that don’t have experience with other language ecosystems, or that have long since forgotten what they’re like, to the point where they’re blind to these sorts of DX shortcomings. The React Hooks / Composition API hard-left-turn smells JUST enough like Python 2 / 3 et al that I’m pretty confident in my estimate of how it’s all going to go down. History repeats, or whatever.
I’ve been tinkering with a lot of mainstream JS frameworks and they pretty much all have their version of this problem.
Next has their new App Directory stuff going on with its own beta docs site. It’s been a few weeks since I looked, so I can’t remember the specifics, but the messaging on the new and old docs sites was not good enough for me to immediately grok what was going on. It also made Googling near impossible.
We got our long-awaited next major version of Nuxt not long ago, too. They seemingly decided that they could just change domains, put a little banner up on the old site, and make the problem go away. Again, makes Googling incredibly hard. I found myself having to remember the design and domain of the old and new sites to know if I’d accidentally stumbled on old documentation. I really want to make Nuxt work for me, but this docs experience left a bad taste in my mouth, a very specific “pre-production” taste, which is really unfortunate given Nuxt’s cadence with v3 stability.
React was about as bad as Next. I found myself bouncing between the stable and beta docs consistently. All the messaging around the stability and supported use cases for Suspense is just…way too impenetrable. I’m a seasoned web application developer. I’m confident that the majority of this isn’t a “me” problem.
The only docs experience I’ve had that comes close to addressing the issue appropriately is the Vue documentation. There’s a nice big switch at the top that switches the docs from favouring the old-school vs composition APIs.
Of course, the underlying problem is React and Vue so solidly keeping their foot in both camps. This is just an outcome of that.
I try my absolute hardest to enter the JS ecosystem with the most open of minds, and there are plenty of people working in this space that are certainly much smarter than me. I just get the impression that there are too many people that don’t have experience with other language ecosystems, or that have long since forgotten what they’re like, to the point where they’re blind to these sorts of DX shortcomings. The React Hooks / Composition API hard-left-turn smells JUST enough like Python 2 / 3 et al that I’m pretty confident in my estimate of how it’s all going to go down. History repeats, or whatever.