Rewrite docs

[szmarczak]

The v11.8.2 docs are a bit outdated. Furthermore, there API changes in #1667. The docs need an update.

To be fixed

• Document types of Object properties #1675
• Maximum allowed response length #617
• Improve docs about Electron support #1473
• Document stream.options #1405
• Improve pagination docs #1053
• ...

Need to mention

• default searchParams not properly merged when requesting searchParams is undefined #1610 (comment)
• If agent fails, try again without #1654 (comment)

To be fixed first

• When transfer encoding is chunked, GOT sometimes does not download full content #1591 & Return error when content-length header does not match bytes transferred #1462
• The types aren't compatible with CommonJS #1137
• Upper limit on the retry backoff #1599
• got.paginate does not call init hooks #1574 - needs a test
• statusCode for responses labeled undefined when promise has a statusCode of 200  #1569

[szmarczak]

Todo:

• update TypeScript docs
• Node.js migration guide
• Axios migration guide

[sindresorhus]

Semi-related to this. Do we have an overview of the breaking changes in v12?

[szmarczak]

Fully? Not yet. Some are mentioned in #1667. I'll write them today.