Background
Let's settle on how we refer to components in our docs, we’re mixing them at the moment. We don’t follow any way consistently though.
In a recent comment on a patch by @bmartinezcalvo, @AnneT raised a point about uppercasing only at begin of sentence for consistency. The currently worked on patch by @DTorsani-WMF goes into an also already introduced casing in a different direction.
Example from current docs:
- Normal buttons have three variants (“flavors”)
But then we’re uppercasing also the weight/variant etc in order to separate and make clear that its describing an attribute of the component:
- Use Quiet Buttons to emphasize Normal Buttons when both are combined on the same page.
And the plot is getting thicker when talking about components like:
- The primary action should be represented by a Primary Progressive Button.
While when talking about the concept of a component, more than the component itself, we’ve lowercased again:
- Reserve destructive buttons for actions that involve removal or limitation, such as deleting a page or blocking a user. Avoid using them for actions like cancel buttons.
Goal
Choose one way and follow it consistently in our public docs and code comments
Open questions
Which of the following options/ways to take?
- Uppercasing first-letter when talking about the Codex component, and lowercasing when speaking of the general concept. E.g. “Use Quiet Buttons to emphasize Normal Buttons… cancel buttons”. That would be my suggestion.
- Uppercasing only components, never attributes/props, e.g. “Use quiet Buttons to emphasizes normal Buttons… cancel buttons”
- Uppercasing only beginning of a sentence, e.g. “Use quiet buttons to emphasizes normal buttons… cancel buttons”
Please note, that
- uppercasing results in a different pronunciation in screen readers, helping them to understand the component concept.
- there’s research has shown that uppercasing helps increase readability, an insightful SO thread