a couple doc improvements / fixes#17702
Conversation
doc/api/documentation.md
Outdated
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
^^^^ non-blocking objection, by the way. Just comments.
doc/api/documentation.md
Outdated
There was a problem hiding this comment.
(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.
There was a problem hiding this comment.
I think it worth keeping on that one.
doc/api/documentation.md
Outdated
Trott
left a comment
Trott
left a comment
There was a problem hiding this comment.
I left some nits/opinions, but overall, seems like an improvement whether or not those nits/opinions are accepted. 😆
doc/api/tty.md
Outdated
There was a problem hiding this comment.
A nit: out of ABC order.
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
For posterity: these are ordered (pretty sure I got it right) in their order of references.
Fishrock123
force-pushed
the
doc-fixes
branch
from
45740ca to
e463ccd
Compare
|
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>
PR-URL: nodejs#17702 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Fishrock123
force-pushed
the
doc-fixes
branch
from
e463ccd to
ce38c49
Compare
Reworded some parts, inter-doc links. PR-URL: #17702 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Also works on directories. PR-URL: #17702 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
PR-URL: #17702 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
PR-URL: #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>
Also works on directories. PR-URL: #17702 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
PR-URL: #17702 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
PR-URL: #17702 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Reworded some parts, inter-doc links. PR-URL: nodejs/node#17702 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Also works on directories. PR-URL: nodejs/node#17702 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
PR-URL: nodejs/node#17702 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
PR-URL: nodejs/node#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>
Also works on directories. PR-URL: #17702 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
PR-URL: #17702 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
PR-URL: #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>
Also works on directories. PR-URL: #17702 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
PR-URL: #17702 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
PR-URL: #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>
Also works on directories. PR-URL: #17702 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
PR-URL: #17702 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
PR-URL: #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>
Also works on directories. PR-URL: #17702 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
PR-URL: #17702 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
PR-URL: #17702 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
4 participants
Checklist
make -j4 test(UNIX), orvcbuild test(Windows) passesAffected core subsystem(s)
doc
Mostly an edit pass over documentation.md but also some fixes to tty.md, fs.md, and synopsis.md.