tomwaterton
commented
5 years ago Copying in @alisonjoseph @designertyler @jeanservaas @shixiedesign @claycrenshaw for info.
Closed tomwaterton closed 5 years ago
tomwaterton
commented
5 years ago Copying in @alisonjoseph @designertyler @jeanservaas @shixiedesign @claycrenshaw for info.
shixiedesign
commented
5 years ago This makes sense to me! Sentence case is also Duo type guidance preferred style so it would be good to see it thoroughly implemented.
jeoffw
commented
5 years ago Hi Tom. I asked @alisonjoseph and @shinytoyrobots to prioritize your input and contributions.
As someone with a developer background, I tend to map title-cased component names directly to code symbol names (e.g. class names). But I do agree that we should be consistent with our own capitalization guidelines!
jnm2377
commented
5 years ago Closing this issue, as we've all agreed to use sentence case, and have made QA PR's for this.
joshhus
commented
4 years ago @tomwaterton Thanks for documenting this issue! It can be difficult to figure out hard rules vs. guidelines, vs prohibitions, however, for special cases.
So when you can, please add an example here, (and in Carbon docs) for the Carbon UI and docs that refer to a Carbon UI, for specifically-named UI elements, property names, code references, categories of objects, etc.
For example, to refer to a named element (specific thing - proper noun rule afaik) in a UI, such as a drop-down list called "Title" >> In docs referring to that object/thing, I might write either, a) "In the UI, select a Title from the drop-down list." or b) "Make a selection from the "Title" drop-down list" ...
One point of view here is that a) above is "better" writing - proactive / active voice (than b) ), so I would expect / hope that capital T Title there is also good practice, to identify Title as the name of a UI element / drop down list (special object, specific one of a kind "thing" in this context. ... And also to avoid the awkwardness of repeating the element name, as in: "In the UI, select a title from the Title drop-down list."
In either case, please document whether capital T in Title in example a) is a 1) hard rule; 2) strictly prohibited or 3) judgment call / choice by product, just be consistent within a product. ?? Thanks!!
tomwaterton
commented
4 years ago Hi @joshhus
The Carbon components and patterns themselves do not require capitalization.
For example, the following examples are both correct:
- Carbon contains a growing set of reusable UI components, including a checkbox component.
- For reference, see the Carbon empty state pattern.
I can't claim to have read every page on the Carbon site (😉), but in general, the capitalization seems to be correct. Here are a few (correct) examples I just pulled at random:
From the notification pattern page:
Designing with notifications When to use Use notifications to inform users of important status changes and updates...
From the button component page:
When using multiple buttons, the primary button appears to the right and any secondary buttons appear to the left.
If your question is about how we refer to labeled elements of a specific product UI (which might have been built using Carbon), then IBM's style rule is this:
When you refer to a UI element, use the same capitalization as used in the UI.
So, in a product UI, if an input field is labeled "Name" then you refer to this as the Name input field. Similarly, if a drop-down menu has the label "Country" next to it, then it is correct to refer to the Country drop-down menu.
A couple of other (correct) examples:
- After you have configured your notification settings, click Next.
- To view more detailed information, click the Status tab.
Capital letters should be reserved for:
If it's not in the list above, it should not be capitalized.
I hope this helps.
FWIW, I recently submitted PR604 (in the carbon-website repo) to add more content guidance - and this includes a whole section on capitalization.
joshhus
commented
4 years ago @tomwaterton thanks! ...
For -- When referring to any UI labels that are themselves capitalized
There is debate about this also - how is it decided correctly a UI label or heading is itself capitalized, such as, "Email address" or "Email Address" for example. ... And if it's not, then how do decide if "Email Address" should be capital A as a proper noun - if it refers to code property or attribute name, for example. It can get into the weeds ...
tomwaterton
commented
4 years ago Hi @joshhus
As mentioned above, I have recently submitted a PR which adds more guidance regarding capitalization to the Carbon website. As the PR (PR604) hasn't been reviewed yet, here is a screengrab from my local build:
(Note: My PR adds more details and examples, but the fundamental principle (to use sentence case throughout the UI) has not changed at all. This is what the current Content guidelines regarding capitalization already state.)
So, as all UI text should use sentence case capitalization, the correct rendering (for the example in your question) is "Email address" - whether that's a field label, link text, table column header, etc.
i.e. a Carbon UI that contained the text "Email Address" would be going against the Carbon capitalization guidelines.
joshhus
commented
4 years ago @tomwaterton Thanks ... Okay so you're also saying that Email Address is never a proper noun, which is a fair argument. But there's confusion around proper nouns as formally-defined code / system attributes, properties etc. (such as "email address") as specific objects or things in a system when they are also general concepts. As a specific property name, it's arguably (or used to be) Email Address (like a name, title, etc. of any person or place, such as Home Depot).
e.g. In capitalizing proper nouns in writing, see the difference between referring to "the Email address attribute" - implies the "address attribute" value of the property named "Email" ... ... vs. "the Email Address attribute" implying the "attribute" value of the property named "Email Address". ... as one example.
So I learned (a while ago, admittedly) that all defined entities in UIs such as field entries in UIs, checkbox names in UIs, etc. are proper nouns. Again in the weeds, and ultimately we'll just follow what Carbon says, but it's not clear right now what Carbon says about system-defined proper nouns. I can submit a req. for them to clearly state the challenging cases also.
joshhus
commented
4 years ago @tomwaterton Very helpful yes, thanks. ... The only remaining question is whether Carbon considers 2-word components as proper nouns, which would mean "Email Address" is the "correct" heading caps in a UI, as opposed to "Email address" (as one example). ... I interpret this as a 2-word proper noun - it's two words, but identifies one, singular specific person, place or thing - i.e. refers to an email address, not an email. ... so example of this would eliminate different interpretations of the proper noun exception to sentence style. i.e. answer "what is a proper noun" within a UI. ... I can add this req. or if you want to LMK ...
tomwaterton
commented
4 years ago Hi @joshhus, I still think you are a little bit confused here...
To be clear:
email address is never a proper noun in any context; it is a common noun, just like any other "thing" (whether that be a concrete thing such as a pen, a plate, a shoe, etc. or an abstract thing such as happiness, security, etc.)But note that completely separate to whether something is a common noun or a proper noun, in our UIs, we use sentence case capitalization, which means that the very first letter of any sentence (or discrete unit of text) is capitalized. And this covers page headings, guidance text, field labels, buttons, nav labels, etc. - everything.
Therefore if it is a field label in the UI, we write Email address - not because this is a proper noun (it is not) but because we apply sentence case capitalization to all text in our UIs.
So, the text Email Address should never appear in any of our UIs because an email address is not a proper noun. It should be written Email address (if it starts a sentence of a discrete unit of text, such as a field label, button, menu item, etc.), or email address if placed anywhere else in the sentence.
The naming conventions of code classes, etc. under the covers might well be different (e.g. it might be labeled emailAddress or whatever), but this should not affect how we write the text in the UI, which should follow standard English.
joshhus
commented
4 years ago @tomwaterton No I'm not confused. Ultimately we will ask Carbon to decide on this, and I'll defer to their decision. - but here's why your assessment is superficial:
You removed "thing" from your definition of a proper noun. Why did you remove thing and place it in a new category?! A proper noun is a specific person place or thing. ... This unfortunately defeats the rest of your argument. My argument is this: you are correct that "email address" generally is not a proper noun, but in this case it's a specific code attribute name - a two word attribute called email + address and not a single word attribute called email.
Of course, sometimes common words are either proper nouns or not, depending on HOW they are used - e.g. president (lower case) is not a proper noun but President of the United States, President is capitalized. ... I read Email Address as a proper noun in the code / UI context. ... Again, ultimately Carbon will decide on this, they are currently unclear on their approach towards attribute names that include multiple words.
One reference:
Common Nouns and Proper Nouns - Grammar Revolution https://www.english-grammar-revolution.com › proper-nouns Since these nouns are naming specific things, they always begin with a capital letter. Sometimes, they contain two or more important words. If this is the case, both important words are capitalized, and the whole thing is still considered to be one noun even though it's made up of more than one word.
tomwaterton
commented
4 years ago Hey @joshhus
Yes, all nouns are "things" in the broadest sense, with proper nouns being a subset. And yes, it is possible to have a proper noun that is made up of more than one word (e.g. Josh Horton, New York, State Farm, etc.)
But none of this changes the fact that terms such as email and address and email address and many, many, many other things that our software products regularly use or reference (container, database, field, model, password, schema, etc., etc.) are and always will be common nouns (regardless of how they might be referred to in code).
You asked the question above:
The only remaining question is whether Carbon considers 2-word components as proper nouns
You'll already know from my earlier responses that I think this question highlights a misunderstanding about what proper nouns are (the number of words is irrelevant), but regardless of the rationale, if you look on the Carbon website today at the list of components you can see that the answer to your question is no - multi-word components are not capitalized (other than the first letter of the first word if at the start of a sentence):
I hope this helps.
p.s. Jan Child and @connor-leech are US-based Content Designers on the Carbon team, so feel free to chat to them if that's more convenient for you.
joshhus
commented
4 years ago Hey @joshhus
Yes, all nouns are "things" in the broadest sense, with proper nouns being a subset. And yes, it is possible to have a proper noun that is made up of more than one word (e.g. Josh Horton, New York, State Farm, etc.)
But none of this changes the fact that terms such as
addressandemail addressand many, many, many other things that our software products regularly use or reference (container,database,field,model,password,schema, etc., etc.) are and always will be common nouns (regardless of how they might be referred to in code).You asked the question above:
The only remaining question is whether Carbon considers 2-word components as proper nouns
You'll already know from my earlier responses that I think this question highlights a misunderstanding about what proper nouns are (the number of words is irrelevant), but regardless of the rationale, if you look on the Carbon website today at the list of components you can see that the answer to your question is no - multi-word components are not capitalized (other than the first letter of the first word if at the start of a sentence):
I hope this helps.
p.s. Jan Child and @connor-leech are US-based Content Designers on the Carbon team, so feel free to chat to them if that's more convenient for you.
Yes I will ask Jan and Connor, thanks, since we are talking past one another. (Shown by the example above listing TYPES of components not the FORMAL NAMES of those components.)
Hello @connor-leech @ Jan Child - Looking for a few proper noun examples to be added to your Carbon docs pages (for purposes of capitalization guidance or rules) at your next opportunity, please, As you know, the status of the NAME (not type) of a product-specific term, text field, module, attribute name, code key-value pair, etc., as a proper noun or not, affects its capitalization in UI and docs. Hence the request for clear guidance to follow Carbon correctly. Thank you, specific discussion and example and reference follow:
The issue is when a product component or element, that is specific to that product, and has a name and specific meaning and reference in that product -- such as a product app name, module name, field name, etc. -- does Carbon allow / require / or forbid such a term to be a proper noun for that product, and therefore all words are capitalized. ... Regardless of the answer, we simply want a clear guideline or rule to follow and reference in Carbon when question arises.
As one example, one might write in docs or UI to identify the user's registered "Email Address" in the UI. Following sentence style rule says "Email address" lowercase address, which is correct assuming "email address" is not a proper noun in this context. ... My background says that it is a proper noun, because in this case we don't mean any one of their likely multiple email addresses, we refer to the specific "Email Address" that has been (or is being) defined in this product-specific environment. In this case it's a specific encoded attribute-value pair, not the general concept of an email address. ... And in this case the attribute name and noun is a two-word phrase, not one - Email Address, not Email. So when a formal and specific person place or "thing" (proper noun definition) is two words, both are capitalized, at least under a traditional model - see reference below.
Below is a reference for the point of view of multi-word proper nouns having all words capitalized. I'm not saying this is a hard rule, we would just like Carbon to clearly define its rule so we implementers don't need to debate it. Please LMK when this Carbon rule or recommendation or guideline for proper nouns is documented:
One reference:
Common Nouns and Proper Nouns - Grammar Revolution https://www.english-grammar-revolution.com › proper-nouns Since these nouns are naming specific things, they always begin with a capital letter. Sometimes, they contain two or more important words. If this is the case, both important words are capitalized, and the whole thing is still considered to be one noun even though it's made up of more than one word.
For background, my name is Tom Waterton and I’m a Content Designer with a fair amount of experience in producing content guidelines (e.g. see ibm.biz/voice-and-tone) and working with designers and product teams within IBM. I’ve had a couple of mtgs with @jeoffw recently and am going to be contributing content input for Carbon from now on.
Summary of issue:
Proposed change:
Note: If others agree with this proposal, I’d be happy to make the text changes myself and submit them. The reason I’ve raised this as an issue and not just submitted a PR is because I wanted to explain the situation and to give others a chance to comment, disagree, etc.
Supporting info:
Background info re capitalization styles:
There is a general trend, both within IBM and across the broader industry to move away from using title case capitalization and to instead use sentence case in most or all UI contexts. For example, ibm.com web pages use sentence case for all UI elements, as do all Hybrid Cloud product UIs. Outside of IBM, companies such as Google also use sentence case capitalization for all UI text (apart from all caps for some buttons). For further details about the pros and cons of different capitalization styles, see here.
Carbon's own guidance re capitalization:
Crucially, Carbon’s own capitalization guidance also recommend using sentence case capitalization for almost all UI elements:
However, the Carbon website nav menu labels don't follow this guidance:
I’ve copied and pasted a subset of the Carbon nav menu labels below:
More about proper nouns
Just in case there is any confusion about what a proper noun is, I thought I’d cover it here. Skip this if you already know!
A proper noun is the name of a particular person (e.g. Paul Rand), place (e.g. Austin, Texas), company / organization (e.g. IBM or Greenpeace), or product (e.g. IBM Watson Studio). Proper nouns name specific one-of-a-kind persons, places, or things, and they begin with capital letters, no matter where they occur within a sentence.
So, the following are proper nouns (and should always be written with an initial capital letter):
The names of UI components are not proper nouns. Terms such as “button” or “link” or “tab” within a UI are all regular, common nouns. They are analogous to words such as “table” or “chair” or “vase”.
So if you are writing guidance about using a particular UI component, you should write the UI component name in lowercase (as you would for any other common noun):
If there is ever a need to differentiate these components from other people’s components you can simply insert “Carbon” as a prefix:
FYI: I also have thoughts on how some of the existing labels and grouping used in the nav menu could be improved, but I will raise a separate issue for those.