Hacker News Reader

Comment by hiphipjorge | Hacker News Reader

Maybe documentation should include uses cases? Newer users to npm + node might think this does something different. Just a suggestions.

View on HN

Maybe documentation for everything should contain use cases, first, before anything.

Every Javascript tool has documentation the wrong way round. Quick start guides and installation instructions are useless if you don't even have a good reason to use the tool in the first place.

Dunno, if you need to be convinced to use a tool, then maybe you aren't yet in the market for said tool. I think it's a cherry on top to describe use-cases but not so critical that there's some sort of ecosystem problem that you describe.

The purpose is to un-convince people from using it. Way too often people have already made up their mind by the time they reach the docs, based purely on how popular the tool is, how flashy the front page is, or whatever bad advice they've received from someone who feels the need to justify their library of choice.

It's good to have critical thinking skills, if people can't figure out if they want to use a tool or not, they should probably work on that a bit!

For sure! Doesn't mean we shouldn't strive to give them a helping hand though. I know I fell victim to the exact same problem when I was learning front-end dev. I'm sure everyone in that space has had a "why on earth have I been using this for the past 6 months?" moment for one library or another. I just feel like we should be taking more preventative measures against that.

Reply on news.ycombinator.com