Comment by cytzol | Hacker News Reader

Comment by cytzol | Hacker News Reader

Parent Full thread

My favourite part of the Webpack 1->2 transition was when they updated their old documentation to say that Webpack 1 was deprecated [0], but failed to mention if the user was currently looking at the Webpack 1 docs or the Webpack 2 docs!

I ended up reading the Webpack 1 documentation for several weeks after 2 came out. I'd see the warning, go "oh, I better not use Webpack 1 then", and continue reading its docs. Cue lots and lots of head scratching.

Webpack developers: if you're going to release a new set of documentation for 3, then please, please make this clear.

[0]: For example, https://webpack.github.io/docs/code-splitting.html. "webpack v1 is deprecated. We encourage all developers to upgrade to webpack 2." There's a link, sure, but I didn't follow it because I had no reason to think I wasn't already on the Webpack 2 docs page. grumble grumble

When I google for "webpack someproblem" then the the first results are usually pointing to the webpack 1 docs. I often don't even find documentation for webpack 2 on the first page, unless I explicitly search for "webpack 2". It took me some time, but now I'm always appending the version number to all my searches. I think Angular has/had the same problem.

Edit: and luckily it's easy to discern the webpack docs: v1 docs look ugly and are lacking information, v2 docs look much nicer and are more detailed ;) They did a great job so far improving the documentation.

Me too. I was shouting "dude, I literally copy pasted you from the docs, you HAVE TO work" at my screen.

I'm glad they are focusing on the ease-of-use. Otherwise, we really would start hiring webpack-developers.

Sometimes I wonder how it would have been if I sticked to Browserify.

Thank God I wasn't the only one. I was having one of those 'am I taking crazy pills' moments before I clicked.

For a tool with arcane concepts and config, the docs mixup was the cuckoo icing on the cake.

Sounds like the varnish docs. https://varnish-cache.org/docs/5.1/users-guide/vcl-grace.htm... would indicated valid config for 5.1 but in fact "fetch" in a "vcl_hit" is not a valid response in 5.1. Should be "miss"

This is (annoyingly) common in a lot of software packages. Protip: Keep your documentation's links canonical. Currently running into the same thing for Polymer. Just keep the old links and do a permanent redirect to Polymer 2.0, with a clear indication of what version you're on. Also looking at Angular here.

same shit with react router

Reply on news.ycombinator.com