Docs: Clarify capitalization rules
Problem to solve
(See related UX epic: &3709)
The style guide has this guidance about capitalization:
https://docs.gitlab.com/ee/development/documentation/styleguide.html#capitalization
It says: Use title case when referring to GitLab Features. For example, Issue Board, Geo, and Runner.
I think there are issues with this guidance:
- It can be hard to determine what, specifically, a feature is. Sometimes it's obvious, but other times not (see examples below).
- If everything is a feature, it can lead to over-capitalization, or a mix, because people aren't sure how to apply the rules.
Proposal
I think we should:
- Come up with specific recommendations for each word and implement them in Vale.
- Lean toward lowercase.
- In the handbook, refer people to the Vale capitalized words list, noting that when you're in doubt, use lowercase.
We can point UX and devs who are writing UI text to this list.
This is just one opinion. This issue is so we can discuss it.
Examples
Here is a list of terms and how I’ve been capitalizing them. Can you let me know what you think?
- Pages (title case) For example: Use GitLab Pages to create a static website from your repo.
- Shared Runner, Group Runner, Specific Runner (title case) I’m torn on this one. To me it makes sense to capitalize Runner, but should we capitalize the three types? shared Runner, group Runner?
- deploy freeze (lowercase) This is new functionality, where you prevent releases during a “deploy freeze window.” Lowercase is my preference.
- release evidence (lowercase) When you create a release, we create a JSON file that lists everything in the release. It’s called release evidence.
- releases (lowercase) For example: In GitLab, when your code is ready to ship, create a release. You can view your releases by going to Project > Releases.
- release assets (lowercase) You can attach release assets to a release.
Other links/references
https://gitlab.slack.com/archives/CDWGE0DDY/p1593187597284200
https://gitlab.slack.com/archives/C03MSG8B7/p1593122377346400
Edited by Mike Lewis