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.

Sign up for GitHub

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

Add branded capitalization guide #36846

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+15 −0
Open

Add branded capitalization guide #36846

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions files/en-us/mdn/writing_guidelines/writing_style_guide/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -253,6 +253,21 @@ Some examples include:
- JavaScript (a trademark of Oracle Corporation, it should always be written as trademarked)
- Python, TypeScript, Django, and other programming languages and framework names

Certain tools or projects have their own branded capitalization. There are three types:

1. **Lowercase**: The name is always lowercase, such as "npm" or "webpack" (see an exception below).
2. **Uppercase**: The name is always uppercase, such as "UNIX", "GNOME", or "VIM".
3. **Mixed case**: The name has a mix of cases, such as "TypeScript", "macOS", or "jQuery".

Always use official capitalization since self-representation is more important than formal language rules. If you are unsure, check the official website or documentation.

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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"npm" is definitely invariant. Under no occasion would you capitalize it—anywhere. It looks awkward anyway. "Webpack" is less strict about this.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

@pepelsbey pepelsbey Nov 18, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

True, there's the following:

npm is a package manager for...

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My two bits.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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".

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd be OK with NPM at the start of a sentence.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


The reason for this exception is to help readers to find the beginning of sentences more easily.

### Contractions

Our writing style tends to be casual, so you should feel free to use contractions (e.g., "don't", "can't", "shouldn't"), if you prefer.
Expand Down