New documentation

Using this is as a mega-issue thread to keep track of our documentation efforts.

Recompose's documentation sucks. All we have is a big Markdown file that describes the API, and a README that is little changed from when I originally wrote it, months ago, in a hurry before publishing to npm.

We need to move the API documentation inline so it's easier to maintain, and we need more documents about the purpose, philosophy, and design of the library.

I propose the following steps:

• Use ESDoc to document the API and generate a doc site. documentationjs was also considered, but I really like the user experience of ESDoc sites. As an example, check out the new docs for RxJS.
• Rewrite the README/Introduction to better position the library as, first and foremost, a functional utility library for React components — not a state management library, or a full replacement for class components, or an entire application architecture.
• Doc which discusses components versus higher-order components versus higher-order components with additional arguments (which we've been calling "helpers" but a better name is welcome).
• Doc on performance, perhaps with a section about component squashing.
• Doc on best practices and pitfalls (how not to use the library). This doc should discuss the preferred pattern of composing multiple higher-order components into an enhance HOC, then applying that to the base component.

I'll update this list with links to separate issues as they are created.