doc: clarifying variables in fs.write()

[jalafel]

Checklist

• [x ] documentation is changed or added
• [ x] commit message follows commit guidelines

Affected core subsystem(s)

doc

Description of change

This commit clarifies variables in the Filesystem docs.
Prior, the documentation for fs.write() had an ambiguous
remark on the parameters of offset and length.

Therefore, this commit makes explicit that the length parameter
in fs.write() is used to denote the number of bytes, which is
a clearer reference for its usage.

Ref: #7868

[Trott]

The variable names in the doc match those in the implementation in lib/fs.js. If we're going to change variable names in the doc, we probably should change them in the implementation as well.

[sam-github]

This caused ambiguity in the meaning, wherein length is traditionally used to denote index length of a data structure. Therefore, this commit rewords length to size, which is a clearer reference for its usage.

I have trouble parsing your sentence, what is the "index length of a data structure"?

I see length and size pretty much as synonyms.

Use in node is consistent with Javascript, I believe: https://developer.mozilla.org/en-US/search?q=length&topic=api&topic=css&topic=html&topic=js&topic=apps&topic=webdev shows length is used as we use it, length also seems to be the preffered word in V8. length also seems common in python, size is arguably more common in C (but the last two aren't really relevant to node.js).

I think the length to size rename is code churn that doesn't materially improve the code or docs. It also changes the tags, so breaks any links from other pages in the API docs and guides.

Your other textual changes look good.

EDIT: I moved conversation back to the source issue #7868 (comment)

[italoacasas]

Landed 762f260