doc: make the style of notes consistent

[aqrln]

• 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?

[Trott]

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]

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

[mhdawson]

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

[aqrln]

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

[mhdawson]

Even, better :)