Add branded capitalization guide #36846
Conversation
github-actions
bot
added
Content:Meta
| The only exception is when the always-lowercase name is at the beginning of a sentence. In this case, use a sentence case. For example: | ||
|
|
||
| - Webpack is a module bundler you can install using npm. | ||
| - Npm can be used to install the webpack module bundler. |
There was a problem hiding this comment.
"npm" is definitely invariant. Under no occasion would you capitalize it—anywhere. It looks awkward anyway. "Webpack" is less strict about this.
There was a problem hiding this comment.
I’ll move the discussion here if you don’t mind, so it won’t get in the way of merging your original PR.
I think it’s important to differentiate self-representation from our project’s writing guidelines. While we should respect the representation, by strictly following the lowercase, we might disrupt the reading flow of our users. If a sentence inside a paragraph or the beginning of a list item doesn’t start with a capital letter, it breaks the flow.
We discussed it with the MDN content team today, so I created this PR.
There was a problem hiding this comment.
Under no occasion would you capitalize it
It looks awkward anyway
Even if it breaks the reading flow for our users? I think we should apply one of the HTML’s design principles here:
In case of conflict, consider users over authors over implementors over specifiers over theoretical purity.
There was a problem hiding this comment.
True, there's the following:
npm is a package manager for...
There was a problem hiding this comment.
Yes, but we are breaking someone else's branding policy. If npm's own docs does this then so should we because they have the final right of interpretation over their brand. Capitalizing the brand name wrong is like spelling a word wrong—capitalization is invariant unless it is explicitly allowed.
There was a problem hiding this comment.
My two bits.
- @estelle suggestion seems very sensible.
- Guidelines are "should" not "must". I'm likely to follow what @pepelsbey said in Add branded capitalization guide #36846 (comment)
- I'd be fine with "Npm" or
npmat the start of a sentence, but not "caseless" npm.
There was a problem hiding this comment.
I'm happy to go along with Estelle's suggestion, but I wouldn't want to endorse the usage of "Npm" under any case—it's certainly a misspelling and arguably much worse than "NPM".
There was a problem hiding this comment.
I'd be OK with NPM at the start of a sentence.
There was a problem hiding this comment.
FWIW Google style guide is to (1) use the product name capitalization if necessary, but (2) prefer to reword so it's not an issue (as Estelle says, and as I would also prefer, aka the cowards' way out): https://developers.google.com/style/product-names. I think this is the best policy.
Even if it breaks the reading flow for our users? I think we should apply one of the HTML’s design principles here:
In case of conflict, consider users over authors over implementors over specifiers over theoretical purity.
I don't think anyone is going to disagree with this principle, but it's not clear which is better for readers - if they always see npm then Npm looks totally weird.
There was a problem hiding this comment.
I'm fine with starting a sentence like this:
npm is a package manager
And if we really want to avoid it, no objections to this either, as suggested above:
You can use npm to XYZ
|
We don't need custom rules. Just install https://www.npmjs.com/package/case-police. I used it for the majority of the fixes anyway. |
Yeah! It will fit perfectly in the pre-commit hook. |
@Josh-Cena may I know why you didn't change I'll submit a followup PR to fix the rest and integrate the tool. |
|
MongoDB should be fixed. AJAX was fixed everywhere except the glossary, where we are consistently using Ajax (and writing "AJAX" as an alternative). UNIX is too widespread and in fact Unix is equally widely used so definitely not worth fixing. |
This warrants an ignore comment at the end of the file.
|
|
Any progress on this? I think we have reached some level of agreement to prefer rewording with npm. |
I tried to fix the bug in the tool, but the library author committed their own fix before merging my PR. Now, the tool has completely lost its ability to use magic comments in markdown files. 😭 @Josh-Cena, could you persuade the author to correct the regex so the tool remains useable with markdown? |
Description
Motivation
Comes from the #36840 and MDN content team discussion.