a couple doc improvements / fixes #17702

Fishrock123 · 2017-12-15T21:59:43Z

Checklist

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

Affected core subsystem(s)

doc

Mostly an edit pass over documentation.md but also some fixes to tty.md, fs.md, and synopsis.md.

Trott · 2017-12-15T22:50:23Z

doc/api/documentation.md

-is not recommended in production environments. Experimental features are not
-subject to the Node.js Semantic Versioning model.
+is not recommended in production environments. **Experimental features are not
+subject to the Node.js Semantic Versioning model.**


I'm generally opposed to adding bold text except in extremely compelling situations. We waaaaaaay overuse typographical emphasis to the point that it has become mostly meaningless.

I'm especially opposed to it here because this is jargon a lot of people won't understand. I know you didn't write this text here, but "are not subject to the Node.js Semantic Versioning model" is vague and kind of misleading. There's nothing Node.js-specific about semantic versioning, and it's not clear that it could correctly be called a model or what that means/implies.

This text is redundant anyway. The very first sentence says things plainly: "subject to non-backwards compatible changes, or even removal, in any future release." Maybe dispense with this last jargon-y sentence and (if we must emphasize something) emphasize that text instead?

^^^^ non-blocking objection, by the way. Just comments.

Trott · 2017-12-15T22:53:17Z

doc/api/documentation.md

 ```txt
 Stability: 2 - Stable
 The API has proven satisfactory. Compatibility with the npm ecosystem
 is a high priority, and will not be broken unless absolutely necessary.
 ```

+*Note*: Caution must be used when making use of `Experimental` features,


(Non-blocking) I'd remove *Note*: here and save it for things that really truly need it. Also remove the **Note**: (note different typography 🙄 ) later in this doc.

I think it worth keeping on that one.

Trott · 2017-12-15T22:53:43Z

doc/api/documentation.md


 ## Syscalls and man pages

 System calls like open(2) and read(2) define the interface between user programs
 and the underlying operating system. Node functions which simply wrap a syscall,
-like `fs.open()`, will document that. The docs link to the corresponding man
+like [`fs.open()`][], will document that. The docs link to the corresponding man
 pages (short for manual pages) which describe how the syscalls work.

 **Note:** some syscalls, like lchown(2), are BSD-specific. That means, for


While in here, some -> Some

Trott

I left some nits/opinions, but overall, seems like an improvement whether or not those nits/opinions are accepted. 😆

vsemozhetbyt · 2017-12-16T00:23:04Z

doc/api/tty.md

+[`net.Socket`]: net.html#net_class_net_socket
+[`process.stdin`]: process.html#process_process_stdin
+[`process.stdout`]: process.html#process_process_stdout
+[`process.stderr`]: process.html#process_process_stderr


A nit: out of ABC order.

Have we actually been enforcing this? I'm kinda clueless - if we have been generally I'll change it, if not... maybe we should do that separately with linting?

Sorry, I thought it was enforced in doc linting or style guide, but it seems I am wrong, I cannot even find PRs that sort references explicitly (I recall there were some). So maybe it is OK as is.

For posterity: these are ordered (pretty sure I got it right) in their order of references.

Fishrock123 · 2017-12-16T18:12:52Z

Lint CI: Edit, oops, again: https://ci.nodejs.org/job/node-test-linter/14546/

Reworded some parts, inter-doc links. PR-URL: nodejs#17702 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

Also works on directories. PR-URL: nodejs#17702 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

PR-URL: nodejs#17702 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

Reworded some parts, inter-doc links. PR-URL: #17702 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>