doc: improvements to fs.markdown copy

[jasnell]

A major reworking of the fs.markdown structure and text.
Moved things around so that they are organized by function,
included additional information so there is less of dependency
on knowledge of the POSIX API.

Other changes:

• Documents .path on fs.ReadStream and fs.WriteStream per
  doc: fs - add path property to Write/ReadStream #4368
• Include coverage of the file system encoding issue
• Example enhancements throughout

This one will be difficult to review, and I apologize for that. @nodejs/documentation @bnoordhuis

[chrisdickinson]

Hm, it looks like GH is suppressing the diff, which may make it hard to leave comments.

[chrisdickinson]

One note I have off the bat is that the error handling bit at the top might be best handled with a link to the appropriate section of the error handling doc.

[chrisdickinson]

This kind of straddles the line between a topic document and a reference document — ideally we'd split this into a "fs" topic doc and a "fs" reference doc, and crosslink between the ref doc and the topic doc. This way we can address questions like "what is a file descriptor and why would I want to manipulate it?" in the topic doc while providing a concise guide for folks who just want to know how to manipulate fds in Node (and, at a broader level, another topic document can address "how do I avoid race conditions" so that this reference doc doesn't have to.)

Taking on the structural changes necessary is somewhat blocked by getting a resolution on #4244, though.

[sam-github]

@jasnell Is there any way of breaking this up into a couple PRs? I'd like to review, but github won't allow, too many changes.

[chrisdickinson]

A thought: could we open a PR to the nodejs/docs repo containing just this file as a single new addition, and do the editing there?

[jasnell]

That could work. This one is a beast
On Jan 30, 2016 12:30 AM, "Chris Dickinson" notifications@github.com
wrote:

A thought: could we open a PR to the nodejs/docs repo containing just
this file as a single new addition, and do the editing there?

—
Reply to this email directly or view it on GitHub
#4486 (comment).