Improve documentation

[mpeyper]

The example in the README is very basic (by design) but there have been numerous queries recently about more advanced usage so I think it's time we expand the documentation to cover these.

Initially, this could be part of the README, but I'd prefer keeping the README fairly light and having a docs directory that can explain features, concepts and techniques in more details (a .md file per topic).

We could look at generating a gitbook, docusaurus, docz or whatever the documentation site flavour of the month is from these docs at some point in the future (unless anyone want to set this up now).

Another thing that I am aware of (from experience 😞) is that docs written by the author are often not very useful to users (especially new users), as there is so much implied understanding that gets baked in. That's why I'm asking for help for others to write these docs. Include any gotchas or hiccups you hit along the way.

It doesn't have to be completely comprehensive from the get-go and we can improve and expand them as we go, so any and all contributions are welcome towards them.

Topics to cover:

• when you should use this library
• when you should NOT use this library
• usage of wrapper (renderHook option)
  • context providers
• usage of initialProps (renderHook option) and the newProps (rerender parameter)
  • dynamic props
  • memoization
• usage of waitForNextUpdate
  • async hooks
  • suspence
  • warnings
• error handling
• recipies
  • common hook patterns (if there are any?)
  • setup with different test runners
• examples
• troubleshooting
  • dom errors (no more dom to cause errors (Use react-test-renderer instead react-testing-library #40)
  • result not changing
• FAQ
  • why do I need .current?
• API

There probably more that can also be included so feel free to go with want makes sense to you. I'm happy to update the checklist if you want to make suggestions in the comments here.

Note: I'm marking these off as we go, but that does not mean what is shown in the work-in-progress site as at all the final version and/or closed to improvements.

[mpeyper]

I've made a start on this. You can see the work-in-progress docs here. I decided to go with docz and so far it's been pretty great. netlify has also been pretty nice for the deployment of the site.

If you want to help and contribute some documentation, the branch is called better-docs.

[mpeyper]

These docs have been released as the official docs now, but still with some "coming soon" pages. I'll leave this open to track any improvements that we want to make to them.

There has also been a suggestion that the current theme (Docz dark theme) is not particularly readable (#107). I've been looking into it the theming for Docz looks a bit, but it's quite fiddly. I'm thinking about just switching to the light theme (in the short term?) or maybe looking at an alternative site generator (docusaurus looks pretty cool).

[mpeyper]

I'm closing this now as the docs have been switched back to the light theme and the "Coming soon" pages have been removed (analytics showed that they were very rarely (like < 5) hit. Happy if someone wants to add them back with some content, but I'm not going to worry.