README 2.x update proposal... take 2

[jkantr]

A continuation of the changes and discussion in #448

This time without broken git history :)

The beginning of a general overhaul of docs to be easier to read, suggest best practices, fix some verbiage, and bring up to date with v2.x

Most suggestions from #448 have either been implemented or added as "comments" in the markdown (TODO 'links')

[codecov-io]

Codecov Report

Merging #504 into master will not change coverage.
The diff coverage is n/a.

@@          Coverage Diff          @@
##           master   #504   +/-   ##
=====================================
  Coverage     100%   100%           
=====================================
  Files           6      6           
  Lines         503    503           
  Branches      158    158           
=====================================
  Hits          503    503

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 09ef40e...2d373bc. Read the comment docs.

[bitinn]

Thx @jkantr, I gave this a quick read and it looks good to me.

@jimmywarting @TimothyGu please give this a quick read when you can, I intend to merge it :)

[bitinn]

Actually one quick thing:

Can you restructure this code block into a table (just like the default header table below).

I always think people overlooks agent options because they are very much hidden in docs, but it's the one option that workaround many problems.

https://github.com/bitinn/node-fetch/blob/2d373bcb77af75876407fdee64fc572e3a08c11a/README.md#options

[jkantr]

@bitinn do you mean something like this?
https://gist.github.com/jkantr/a8036d22b6aaec0626ae2340a1aaf1e2

Tables are pretty awkward to work with in .md unfortunately... maybe we could just have a separate sub header about what problems can be solved by using manual agents?

[bitinn]

@jkantr yeah, I would move the fetch standard column into a header row, or simply have 2 tables.

If you already got another solution in mind, make a gist, we will take a look. My problem is mainly with (1) the code block isn't great for quick scanning; (2) the explanation on non-standard options could be better.

[jkantr]

Colspan doesn't really work it seems (can't span the first col, only the ones after) in GFM so this was as close as I can get https://gist.github.com/jkantr/a8036d22b6aaec0626ae2340a1aaf1e2

It may be better just to stuff them in a table and explain each in its own #### section after

[bitinn]

It may be better just to stuff them in a table and explain each in its own #### section after

Whichever you see fit, really, I don't have a strong preference on using tables, just the first thing that came to my mind.

[bitinn]

@jkantr @jimmywarting @TimothyGu hey guys, last call, I am going to merge this PR, as is, please give OP a thumb up if you feel this is ok. And stop me if you see anything straight up wrong.

[jimmywarting]

It was good.
You took all other feedback and consideration into account and forged a darn good documentation, like the hole ToC thing!

I didn't read carefully in the end just shimmed thought the rest. Will just say that all looks alright!
So I thought it became to much at the end... there where a lot of things packed into one readme file.
So here are my thoughts: Have a Readme that describes what the fetch api is (and isn't) and then use the github's wiki page

[styfle]

there where a lot of things packed into one readme file

The way we solve this problem with marked is to put the description and a simple getting started snippet in the README (this gets installed millions of times so we keep it small).

The README has a link to GitHub pages which hosts the full documentation (stored in /docs in the repo).

[bitinn]

OK I am merging this, any issue we will fix in future PR