-
Notifications
You must be signed in to change notification settings - Fork 30.1k
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
Comments
Yes, let's make them consistent. ❤️ 👍 I don't think it matters which style we go for other than a capital letter after the 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 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). |
@Trott SGTM, I'll do it right now. Thanks for the detailed response :) |
+1 to pick a style, submit PR to doc/STYLE_GUIDE.md, and then update based on what's agreed in the PR :) |
Even, better :) |
Make the style of "Note:" paragraphs consistent and document the guidelines in `doc/STYLE_GUIDE.md`. Fixes: nodejs#13131
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]>
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
?The text was updated successfully, but these errors were encountered: