points by logicallee 8 years ago

This web site doesn't follow best practices of not saying what it is, not giving any examples, not letting you see it in action, making users have to read through outdated, long manuals that if you follow directly you get unexplained error messages you have to Google, needing to watch and follow along with a 15 minute youtube video whose first 10 minutes talk about the different choices of IDE's that you have, how to download and save a file from the Internet, and finally whose last 5 minutes do something obscure and contrived, that is the the wrong way to do something.

In fact, if you go to reactjs.org, within the first 7 seconds you can see live examples. (By scrolling down.) If you click the prominent "get started" button prominent at the top of the page, you get taken to a page that says "The easiest way to get started with React is to use this Hello World example code on CodePen" and a single click gets you there. The intro tutorial itself quickly walks you through everything, gearing up from basics to an advanced summary quickly in a well-structured way. It has a "help I'm stuck!" section that tells you exactly what you need to do if you are stuck.

This needs to die.

Someone needs to go about writing some half-assed documentation and putting it up on github without any usable links.

Information is meant to be hidden, and the role of documentation, such as reactjs.org, is properly to hide the nuggets of usable information among false starts, unexplained terminology, long flowing paragraphs of flowery prose that reduce to "", important notes that can only affect people who already know everything else about the thing in question, such as information about upgrades and transitions, and just generally give the sort of impression you get when you read through useless government paperwork.

Take note, people. if you make a site like this, then you can end up being the best-adopted and most popular solution in your entire industry - that's no way to program. Documentation is meant to be a hurdle, a kind of euthanasia program that takes enthusiastic new visitors and tears out their enthusiasm, destroys their will to live, and grinds them down with prose.