doc: improve fs doc intro

[jasnell]

/cc @Trott

Checklist

• make -j4 test (UNIX), or vcbuild test (Windows) passes
• documentation is changed or added
• commit message follows commit guidelines

[mscdex]

I think the comparison between "asynchronous" and Promise-based APIs could be confusing. The Promise-based APIs definitely are asynchronous, they're just not the callback-based API.

[jasnell]

@mscdex updated to address your concern

[Trott]

Not blocking on it, but I'm 👎 on the capitalization in Promise-based. The only justification I can think of is that it emphasizes the underlying Promise class. I think that draws attention to the wrong thing (implementation detail) in promise-based.

For what it's worth, MDN agrees, based on the contents of https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Asynchronous/Promises (where promise-based appears 7 times and Promise-based not at all).

I also interpret the Microsoft style guide section on capitalization as falling on the "when in doubt, don't capitalize" side of things.

[Trott]

I removed the author ready label in light of lpinca's comment and my comment, but I think this is ready to land. I don't think either of those comments are blocking (I know mine isn't and they approved the PR despite the comment they left suggesting a chance.)

[github-actions]

Commit Queue failed

- Loading data for nodejs/node/pull/34843
✔  Done loading data for nodejs/node/pull/34843
----------------------------------- PR info ------------------------------------
Title      doc: improve fs doc intro (#34843)
Author     James M Snell  (@jasnell)
Branch     jasnell:new-fs-doc-improvements -> nodejs:master
Labels     author ready, doc, fs
Commits    1
 - doc: improve fs doc intro
Committers 1
 - James M Snell 
PR-URL: https://github.com/nodejs/node/pull/34843
Reviewed-By: Anna Henningsen 
Reviewed-By: Ricky Zhou <[email protected]>
Reviewed-By: Anto Aravinth 
Reviewed-By: Luigi Pinca 
------------------------------ Generated metadata ------------------------------
PR-URL: https://github.com/nodejs/node/pull/34843
Reviewed-By: Anna Henningsen 
Reviewed-By: Ricky Zhou <[email protected]>
Reviewed-By: Anto Aravinth 
Reviewed-By: Luigi Pinca 
--------------------------------------------------------------------------------
   ⚠  Commits were pushed since the last review:
   ⚠  - doc: improve fs doc intro
   ✖  No CI runs detected
   ℹ  This PR was created on Wed, 19 Aug 2020 19:59:53 GMT
   ✔  Approvals: 4
   ✔  - Anna Henningsen (@addaleax): https://github.com/nodejs/node/pull/34843#pullrequestreview-470845622
   ✔  - Ricky Zhou (@rickyes): https://github.com/nodejs/node/pull/34843#pullrequestreview-471545184
   ✔  - Anto Aravinth (@antsmartian): https://github.com/nodejs/node/pull/34843#pullrequestreview-472057857
   ✔  - Luigi Pinca (@lpinca): https://github.com/nodejs/node/pull/34843#pullrequestreview-472762285
--------------------------------------------------------------------------------
   ✔  Aborted `git node land` session in /home/runner/work/node/node/.ncu

[jasnell]

Landed in 010383a