Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: make the style of notes consistent #13131

Closed
aqrln opened this issue May 20, 2017 · 5 comments
Closed

doc: make the style of notes consistent #13131

aqrln opened this issue May 20, 2017 · 5 comments
Labels
doc Issues and PRs related to the documentations. question Issues that look for answers.

Comments

@aqrln
Copy link
Contributor

aqrln commented May 20, 2017

  • Version: master
  • Platform: all
  • Subsystem: doc

At the moment we have a number of paragraphs starting with Note: in the API docs, but they tend to be stylistically inconsistent. The majority of them use a capital letter after the "Note:" tag itself, but some of them don't; some of them use bold formatting and some of them italic, moreover, sometimes only the "Note" word itself is made bold or italic, but in other cases the whole paragraph is.

Should we make it consistent, and if yes, which style should we stick to and document in doc/STYLE_GUIDE.md?

@aqrln aqrln added doc Issues and PRs related to the documentations. question Issues that look for answers. labels May 20, 2017
@Trott
Copy link
Member

Trott commented May 20, 2017

Yes, let's make them consistent. ❤️ 👍

I don't think it matters which style we go for other than a capital letter after the : is definitely the way to go (unless the first word is an identifier like a variable name where capitalizing it changes it).

As far as italics vs. bold vs. no typographic modification, that's probably a matter of opinion. You could just do whatever is most common in the docs already, or whatever looks good to your eye. Personally, I'd go for no typographic modification because if a note is important, it probably shouldn't be a note, but rather a regular paragraph.

In fact, that could be another step in this process: Remove the Note: designation and just make the thing its own paragraph wherever that makes sense. Heck, it might be everywhere.

Anyway, I like no typographic modification because the more you use bold and italic, the less meaningful they become as highlights for important things. That said, if we must have one or the other, I prefer bold in this case, but really anything is fine as far as I'm concerned.

I believe @jasnell was on a mission at some point to make the notes all typographically identical. I suspect he'd be happy to offload that someone else. I also suspect that while he has opinions about the bold vs. italics vs. nothing decision, what he probably wants most is consistency.

He's capable of speaking for himself, of course, but as far as I'm concerned: Pick a style and run with it. It will probably be the subject of enormous bike-shedding in the PR, so maybe just do something and we can bike-shed there, rather than needing to bike-shed twice (one in this issue and then again in the PR).

@aqrln
Copy link
Contributor Author

aqrln commented May 20, 2017

@Trott SGTM, I'll do it right now. Thanks for the detailed response :)

@mhdawson
Copy link
Member

+1 to pick a style, submit PR to doc/STYLE_GUIDE.md, and then update based on what's agreed in the PR :)

@aqrln
Copy link
Contributor Author

aqrln commented May 23, 2017

@mhdawson there's no problem with doing this as one step :)
See #13133

@mhdawson
Copy link
Member

Even, better :)

aqrln added a commit to aqrln/node that referenced this issue May 24, 2017
Make the style of "Note:" paragraphs consistent and document the
guidelines in `doc/STYLE_GUIDE.md`.

Fixes: nodejs#13131
@addaleax addaleax reopened this May 24, 2017
@refack refack closed this as completed in 2af49b6 May 25, 2017
jasnell pushed a commit that referenced this issue May 28, 2017
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 <[email protected]>
Reviewed-By: Luigi Pinca <[email protected]>
Reviewed-By: Daijiro Wachi <[email protected]>
Reviewed-By: Michael Dawson <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Sam Roberts <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
doc Issues and PRs related to the documentations. question Issues that look for answers.
Projects
None yet
Development

Successfully merging a pull request may close this issue.

4 participants