doc: make the style of notes consistent #13133

aqrln · 2017-05-20T20:40:03Z

Make the style of "Note:" paragraphs consistent and document the guidelines in doc/STYLE_GUIDE.md.

I picked the style that I find reasonable and which I had used once adding a note myself, but I don't have any strong opinions about the notes style except that it should be only one, so the formatting may be discussed in this PR.

Checklist

documentation is changed or added
commit message follows commit guidelines

Affected core subsystem(s)

doc

aqrln · 2017-05-20T20:42:22Z

doc/api/domain.md

@@ -115,7 +115,7 @@ if (cluster.isMaster) {
    d.on('error', (er) => {
      console.error(`error ${er.stack}`);

-      // Note: we're in dangerous territory!
+      // Note: We're in dangerous territory!


Note: that falls outside the scope of this PR, but "we" shouldn't have been used here at all. I'll reword all of the comments in this example in another PR.

aqrln · 2017-05-20T20:44:18Z

doc/api/events.md

@@ -142,7 +142,7 @@ myEmitter.emit('error', new Error('whoops!'));

 To guard against crashing the Node.js process, a listener can be registered
 on the [`process` object's `uncaughtException` event][] or the [`domain`][] module
-can be used. (_Note, however, that the `domain` module has been deprecated_)
+can be used. _(Note, however, that the `domain` module has been deprecated.)_


And what about this case, to my perception, this is not a note as in "Note:", but rather just a regular sentence. I fixed the stylistic mistakes while I was here, though.

Agreed. AFAICT this is an editorial comment that happens to start with the word "note".
~~But it should be "Note however," no first comma.~~

I am not a native speaker, but as for me, the punctuation around "however" is pretty valid here as is.

I agree that Note, however, that... is perfectly fine (and to my sense, preferable). I do think that note should probably _not* be italicized, though.

refack

LGTM.
Rubber stamp completeness...

Trott · 2017-05-20T22:36:54Z

doc/STYLE_GUIDE.md

@@ -58,6 +58,11 @@
 * References to constructor functions should use PascalCase
 * References to constructor instances should be camelCased
 * References to methods should be used with parentheses: `socket.end()` instead of `socket.end`
+* In order to make a note that a reader should draw special attention to,


I think this would be somewhat better as To draw special attention to a note,

Done, thanks.

lpinca · 2017-05-21T06:15:32Z

doc/api/net.md


-* All [`net.Socket`][] are set to `SO_REUSEADDR` (See [socket(7)][] for


Nit: I understand this goes against the style defined above but isn't it better to keep the bulleted list here instead of repeating Note: in two consecutive lines?

lpinca · 2017-05-21T06:24:18Z

doc/api/tls.md

-    generated from `process.argv`, other APIs that create secure contexts
-    have no default value.
+
+**Note:** [`tls.createServer()`][] sets the default value of the


Nit: it might makes sense to also use a bulleted list here.

aqrln · 2017-05-22T13:19:02Z

ping @nodejs/collaborators

Before we really start enforcing it, I think we need to make sure that others are acknowledged about this and I'd like to hear more opinions about the preferred style, specifically re: questions like bold vs italic, should we group consequent notes into unordered lists, etc.

refack · 2017-05-22T13:25:02Z

Just a few refs that use **Note:**

watilde · 2017-05-22T13:28:04Z

+1 on this, and it would be nicer if we could have this addition as one of the actual link rules.

Refs: tools: introduce make mdlint command and tools #12756

jasnell · 2017-05-22T14:32:12Z

doc/STYLE_GUIDE.md

@@ -58,6 +58,10 @@
 * References to constructor functions should use PascalCase
 * References to constructor instances should be camelCased
 * References to methods should be used with parentheses: `socket.end()` instead of `socket.end`
+* To draw special attention to a note, adhere to the following guidelines:


To be quite honest, I generally prefer the *Note*: style and have been incrementally working towards that for quite some time. I guess this is fine tho. Mildly -0

As I said,

I don't have any strong opinions about the notes style except that it should be only one, so the formatting may be discussed in this PR.

I am completely fine with changing the style to what you prefer, a Vim macro will chew it easily 😄

aqrln · 2017-05-22T15:08:29Z

@watilde yeah, I am really looking forward to see the markdown linter landed. Sure, we can make a rule for that. Aside from this PR, ensuring that we use 80-character wrapping (except changelogs) and em-dashes are on my to-do list.

mhdawson

LGTM

Make the style of "Note:" paragraphs consistent and document the guidelines in `doc/STYLE_GUIDE.md`. Fixes: nodejs#13131

aqrln · 2017-05-24T15:12:38Z

I've updated the PR. The first commit is the original commit rebased onto master with conflicts resolved and with a couple of notes that I missed before (or that weren't present before the rebase, idk) updated to conform to the general style. The second commit changes the style to what @jasnell prefers and the third commit follows the suggestion by @lpinca to use bulleted lists for consecutive notes.

@refack @lpinca @watilde @mhdawson can you please take another look and say whether this still LGTY? Thanks!

refack · 2017-05-24T15:38:52Z

-0.5 on *Note*:
+1 on **Note:**

Waiting for consensus on bullet lists for https://github.com/nodejs/node/pull/13173/files#diff-acabf706a8aa070a8796e3573f7e4678

sam-github

Nice, thanks.

lpinca · 2017-05-24T16:06:45Z

Still LGTM.

addaleax · 2017-05-24T18:14:39Z

~~Landed in 04e9dcb3f392f66b3d1e5c006f7be227297f8b8c~~

addaleax · 2017-05-24T18:33:04Z

Reopened, seems like I was too fast here.

refack · 2017-05-24T19:07:02Z

@jasnell how strongly do you feel on the *Note* vs **Note** style? Seems to me like it's only the two of us that have a preference...

addaleax · 2017-05-24T19:09:14Z

I’m +1 to *Note*.

refack · 2017-05-25T22:46:47Z

I yield. I see two explicit +1 for *Note*: and there's @Trott's #13131 (comment)

refack

👍 to *Note*: style.

refack · 2017-05-25T23:10:48Z

~~Landed in 2af49b6~~

Make the style of "Note:" paragraphs consistent and document the guidelines in `doc/STYLE_GUIDE.md`. PR-URL: nodejs#13133 Fixes: nodejs#13131 Reviewed-By: Refael Ackermann <refack@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Daijiro Wachi <daijiro.wachi@gmail.com> Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Sam Roberts <vieuxtech@gmail.com>

refack · 2017-05-25T23:12:11Z

Landed in 2af49b6

Make the style of "Note:" paragraphs consistent and document the guidelines in `doc/STYLE_GUIDE.md`. PR-URL: #13133 Fixes: #13131 Reviewed-By: Refael Ackermann <refack@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Daijiro Wachi <daijiro.wachi@gmail.com> Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Sam Roberts <vieuxtech@gmail.com>

MylesBorins · 2017-07-17T16:49:50Z

This does not land cleanly in LTS. Please feel free to manually backport. Please also feel free to replace do-not-land if it is being backported

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

aqrln commented May 20, 2017

View reviewed changes

refack approved these changes May 20, 2017

View reviewed changes

Trott reviewed May 20, 2017

View reviewed changes

lpinca approved these changes May 21, 2017

View reviewed changes

watilde approved these changes May 22, 2017

View reviewed changes

jasnell reviewed May 22, 2017

View reviewed changes

aqrln mentioned this pull request May 23, 2017

doc: make the style of notes consistent #13131

Closed

mhdawson approved these changes May 23, 2017

View reviewed changes

refack mentioned this pull request May 23, 2017

doc: How to publish N-API package nodejs/nodejs.org#1236

Merged

aqrln added 3 commits May 24, 2017 17:00

doc: make the style of notes consistent

a2e644f

Make the style of "Note:" paragraphs consistent and document the guidelines in `doc/STYLE_GUIDE.md`. Fixes: nodejs#13131

squash! change the style to italic

2dc7c14

squash! address @lpinca's suggestion

f7db525

aqrln force-pushed the doc-consistent-notes branch from 16b3231 to f7db525 Compare May 24, 2017 15:06

jasnell approved these changes May 24, 2017

View reviewed changes

refack mentioned this pull request May 24, 2017

fs: expose Stats times as Numbers #13173

Merged

4 tasks

sam-github approved these changes May 24, 2017

View reviewed changes

addaleax closed this May 24, 2017

addaleax reopened this May 24, 2017

refack approved these changes May 25, 2017

View reviewed changes

refack self-assigned this May 25, 2017

refack closed this May 25, 2017

aqrln deleted the doc-consistent-notes branch May 25, 2017 23:16

jasnell mentioned this pull request May 28, 2017

8.0.0 Release Proposal #12220

Closed

This was referenced Jun 6, 2017

util: add util.callbackify() #12712

Merged

Chore: Header-ify the Install instructions nodejs/node-gyp#1225

Closed

This was referenced Jun 13, 2017

doc: note that fs.futimes only works on AIX >7.1 #13659

Closed

Auditing for 6.11.1 nodejs/Release#230

Closed

refack mentioned this pull request Jul 8, 2017

doc: add note to tty.WriteStream event 'resize' on Windows #13576

Closed

MylesBorins added the dont-land-on-v6.x label Jul 17, 2017

refack removed their assignment Oct 20, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: make the style of notes consistent #13133

doc: make the style of notes consistent #13133

aqrln commented May 20, 2017

aqrln May 20, 2017 •

edited

Loading

aqrln May 20, 2017

refack May 20, 2017 •

edited

Loading

aqrln May 20, 2017

Trott May 20, 2017

refack May 20, 2017

refack left a comment

Trott May 20, 2017

aqrln May 20, 2017

lpinca May 21, 2017

lpinca May 21, 2017

aqrln commented May 22, 2017

refack commented May 22, 2017

watilde commented May 22, 2017

jasnell May 22, 2017

aqrln May 22, 2017

aqrln commented May 22, 2017

mhdawson left a comment

aqrln commented May 24, 2017

refack commented May 24, 2017

sam-github left a comment

lpinca commented May 24, 2017

addaleax commented May 24, 2017 •

edited

Loading

addaleax commented May 24, 2017

refack commented May 24, 2017

addaleax commented May 24, 2017

refack commented May 25, 2017

refack left a comment

refack commented May 25, 2017 •

edited

Loading

refack commented May 25, 2017

MylesBorins commented Jul 17, 2017


		* All [`net.Socket`][] are set to `SO_REUSEADDR` (See [socket(7)][] for

doc: make the style of notes consistent #13133

doc: make the style of notes consistent #13133

Conversation

aqrln commented May 20, 2017

Checklist

Affected core subsystem(s)

aqrln May 20, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

refack May 20, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

refack left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

aqrln commented May 22, 2017

refack commented May 22, 2017

watilde commented May 22, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

aqrln commented May 22, 2017

mhdawson left a comment

Choose a reason for hiding this comment

aqrln commented May 24, 2017

refack commented May 24, 2017

sam-github left a comment

Choose a reason for hiding this comment

lpinca commented May 24, 2017

addaleax commented May 24, 2017 • edited Loading

addaleax commented May 24, 2017

refack commented May 24, 2017

addaleax commented May 24, 2017

refack commented May 25, 2017

refack left a comment

Choose a reason for hiding this comment

refack commented May 25, 2017 • edited Loading

refack commented May 25, 2017

MylesBorins commented Jul 17, 2017

aqrln May 20, 2017 •

edited

Loading

refack May 20, 2017 •

edited

Loading

addaleax commented May 24, 2017 •

edited

Loading

refack commented May 25, 2017 •

edited

Loading