doc: edit for concision #17891

Trott · 2017-12-28T03:23:24Z

This removes some wordy phrases (notably "it is important to note that")
and a few instances of typographical excess (a bulleted list where
separate paragraphs for each bullet item suffice, unneeded italics,
etc.).

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

This removes some wordy phrases (notably "it is important to note that") and a few instances of typographical excess (a bulleted list where separate paragraphs for each bullet item suffice, unneeded italics, etc.).

joyeecheung · 2017-12-28T07:06:22Z

doc/api/async_hooks.md

-*Note*: It is important that `before`/`after` calls are unwound
-in the same order they are called. Otherwise an unrecoverable exception
-will occur and the process will abort.
+`before` and `after` calls are unwound in the same order they are called.


I think this should be ..calls must be unwound... since it's a note for the implementers.

joyeecheung · 2017-12-28T07:07:42Z

doc/api/process.md

+An easy way to send the `SIGINT` signal is with `<Ctrl>-C` in most terminal
+programs.
+
+`SIGUSR1` is reserved by Node.js to start the [debugger][]. It's possible to


I actually prefer the list, it would also be easier to read if these are listed in a table.

Restored the bulleted list. A table is a great idea if we can do it in a way that the information is still readable in raw markdown. If someone reading this wants to pick that piece up and make a separate PR, go for it. :-D

gibfahn

LGTM modulo @joyeecheung 's suggestions.

BridgeAR · 2017-12-28T14:38:23Z

@Trott i know you dislike the "note" parts a lot but I wonder if we might just discuss this again in general:

If I read docs I want to know immediately what is important. Having a highlight per individual part makes therefore sense to me because I know what to expect, even when just glancing over the documentation.
I do not feel like the individual note loses it's importance because there are many of them. But it can of course be me alone who feels that way.

vsemozhetbyt · 2017-12-28T21:27:13Z

doc/api/process.md

-signal `0` can be used to test for the existence of a process. Sending `SIGINT`,
-`SIGTERM`, and `SIGKILL` cause the unconditional termination of the target
-process.
+An easy way to send the `SIGINT` signal is with `<Ctrl>-C` in most terminal


In this fragment we have:
<Ctrl>-C
CTRL+C
<Ctrl>+<Break>
Do we need to unify this?

The two mentions of Ctrl-C are redundant, so I'd be inclined to remove this one. Which I'll do.

I made the other two instances consistent. Probably worth figuring out what (if any) universal standard there is for such things (like maybe see what RFCs do), document it in the style guide, and apply it across all docs. But not in this PR. :-D

vsemozhetbyt · 2017-12-28T21:29:08Z

doc/api/process.md

+install a listener but doing so will _not_ stop the debugger from starting.
+
+`SIGTERM` and `SIGINT` have default handlers on non-Windows platforms that
+resets the terminal mode before exiting with code `128 + signal number`. If


resets -> reset ?

Yes, changed, thanks!

Trott · 2017-12-28T21:47:46Z

If I read docs I want to know immediately what is important. Having a highlight per individual part makes therefore sense to me because I know what to expect, even when just glancing over the documentation.

@BridgeAR You are right to caution against throwing out the proverbial baby with the bath water. I think we have four inter-related problems with our Note stuff.

A lot of them are not important. Many are edge cases or trivia. They might be important to a few people but they are not important to most people. Having lots of notes like that ends up diluting the notes that actually matter. (For example, the fact that fs.rmdir() returns different errors if it is used on a file instead of a directory is an edge case, not an important note. Worth documenting? Yup. Worth emphasizing? Nope.)
Typographically, we don't do anything that helps our notes stand out. They look more like footnotes and seem de-emphasized. Without using your browser's search function, try to scan https://nodejs.org/api/fs.html quickly for Note instances and see how many you can find. There are 29. Good luck finding more than one or two. (Probable counterargument: One doesn't scan the whole doc typically. More typically, one scans a single event or method. The notes are more findable that way. I would argue, though, that most of our entries are sufficiently short that using Note for emphasis isn't helpful in those instances anyway. In any event, typography is easy to change so this is fixable.)
There are too many of them. What would entail "not too many" is a good question. I would counter that the answer lies with...
There is no clear criteria for what warrants a Note. The fact that fs.utimes() does not work on AIX gets a Note, but the fact that recursive fs.watch() does not work on AIX does not get a Note. Basically, what gets a Note is left entirely up to author discretion, and people's ideas about what belongs in a Note seems to vary wildly. If we could come up with a short allow-list of things that are permissible to treat with Note in our style guide, it would probably be the way to go. Then, if there are things that warrant Note but that aren't covered, we can update the style guide. I'm not sure how much we can establish concrete rules here, but IMO it would be nice if there was less discretion on these.

Trott · 2017-12-28T21:50:10Z

@BridgeAR By the way, if you had your druthers, which of the four instances of Note this change set would be restored? I'm thinking the async_hooks is pretty important (common pitfall worth noting) so maybe that one could/should be restored, but the others not so much.

BridgeAR · 2017-12-28T23:03:15Z

I agree that not all entries here are necessary but I do not see a negative impact of those "unnecessary" ones either. And I agree that reverting at least the async_hooks part would be good.

gibfahn · 2017-12-28T23:14:27Z

I agree with @Trott that Note is only useful if it highlights something you're likely to want to be warned about, if we're exhorting the user to make sure to read this paragraph, it should be something particularly important or surprising.

If I read docs I want to know immediately what is important. Having a highlight per individual part makes therefore sense to me because I know what to expect, even when just glancing over the documentation.

This is exactly what I'd expect Note: to be used for. However I think if they're mostly minor details then scanning through and just reading the Note: part becomes a bit pointless, you're just accumulating trivia about the APIs rather than understanding their gotchas.

For example:

Note: Windows does not support sending signals,

This whole API is mostly non-applicable to windows, seems like something you'd want to push in the user's face.

Note: An easy way to send the SIGINT signal is with <Ctrl>-C in most terminal programs.

Seems like a useful hint, but not something that needs to be specially called out here.

Typographically, we don't do anything that helps our notes stand out. They look more like footnotes and seem de-emphasized.

If we reduce the Note:s to those that are actually worth emphasizing, then why not put them in bold?

Note: seems to stand out a bit better.

jasnell · 2017-12-28T23:39:09Z

Btw... the entire point of moving the *Note*: syntax in the notes was to first get a consistent style for all of these kinds of sidebar type notes so that they could be more easily found and replaced with something better later on when a better approach was determined.

Trott · 2017-12-30T17:22:14Z

@BridgeAR I've restored three of the four Note annotations that were originally removed. I removed the Cntl-C tip one entirely because that information was already in the bulleted list. PTAL.

Trott · 2018-01-01T04:45:01Z

CI: https://ci.nodejs.org/job/node-test-pull-request-lite/61/

This removes some wordy phrases (notably "it is important to note that"). PR-URL: nodejs#17891 Reviewed-By: Gibson Fahnestock <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Joyee Cheung <[email protected]>

Trott · 2018-01-04T01:19:25Z

Landed in 26607b8

This removes some wordy phrases (notably "it is important to note that"). PR-URL: #17891 Reviewed-By: Gibson Fahnestock <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Joyee Cheung <[email protected]>

doc: edit for concision

8374657

This removes some wordy phrases (notably "it is important to note that") and a few instances of typographical excess (a bulleted list where separate paragraphs for each bullet item suffice, unneeded italics, etc.).

nodejs-github-bot added the doc Issues and PRs related to the documentations. label Dec 28, 2017

joyeecheung reviewed Dec 28, 2017

View reviewed changes

gibfahn approved these changes Dec 28, 2017

View reviewed changes

cjihrig approved these changes Dec 28, 2017

View reviewed changes

vsemozhetbyt reviewed Dec 28, 2017

View reviewed changes

Trott added 5 commits December 30, 2017 09:07

squash

465874d

squash

ba7d74d

squash

71af80b

squash

8d2af16

squash

004033a

squash

ba1195b

joyeecheung approved these changes Jan 1, 2018

View reviewed changes

Trott closed this Jan 4, 2018

MylesBorins mentioned this pull request Jan 10, 2018

v9.4.0 proposal #18069

Merged

MylesBorins added dont-land-on-v6.x labels Jan 24, 2018

Trott deleted the no-it-is-not branch January 13, 2022 22:48

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: edit for concision #17891

doc: edit for concision #17891

Trott commented Dec 28, 2017

joyeecheung Dec 28, 2017

joyeecheung Dec 28, 2017

Trott Dec 30, 2017

gibfahn left a comment

BridgeAR commented Dec 28, 2017

vsemozhetbyt Dec 28, 2017

Trott Dec 30, 2017

vsemozhetbyt Dec 28, 2017 •

edited

Loading

Trott Dec 30, 2017

Trott commented Dec 28, 2017 •

edited

Loading

Trott commented Dec 28, 2017

BridgeAR commented Dec 28, 2017

gibfahn commented Dec 28, 2017

jasnell commented Dec 28, 2017

Trott commented Dec 30, 2017

Trott commented Jan 1, 2018

Trott commented Jan 4, 2018

doc: edit for concision #17891

doc: edit for concision #17891

Conversation

Trott commented Dec 28, 2017

Checklist

Affected core subsystem(s)

joyeecheung Dec 28, 2017

Choose a reason for hiding this comment

joyeecheung Dec 28, 2017

Choose a reason for hiding this comment

Trott Dec 30, 2017

Choose a reason for hiding this comment

gibfahn left a comment

Choose a reason for hiding this comment

BridgeAR commented Dec 28, 2017

vsemozhetbyt Dec 28, 2017

Choose a reason for hiding this comment

Trott Dec 30, 2017

Choose a reason for hiding this comment

vsemozhetbyt Dec 28, 2017 • edited Loading

Choose a reason for hiding this comment

Trott Dec 30, 2017

Choose a reason for hiding this comment

Trott commented Dec 28, 2017 • edited Loading

Trott commented Dec 28, 2017

BridgeAR commented Dec 28, 2017

gibfahn commented Dec 28, 2017

jasnell commented Dec 28, 2017

Trott commented Dec 30, 2017

Trott commented Jan 1, 2018

Trott commented Jan 4, 2018

vsemozhetbyt Dec 28, 2017 •

edited

Loading

Trott commented Dec 28, 2017 •

edited

Loading