Fix 'GitLab' brand name #540
Conversation
Vercel Previews Deployed
|
|
This is great, @hsnabszhdn, thank you. I would like to encourage going one step further: How do we ensure that this is not repeated in new documentation? Is there a way to lint our documentation? Without such an automated step, I am worried this one off effort might need to be repeated over and over. Importantly, I am not blocking change, but suggest to add another (possibly in a separate PR) |
|
Good point @nikolasrieble! To be honest, this is the first time I open this repo, and I wasn't able to run the code locally. The README file doesn't seem to be publicly usable. It needs logging in to Vercel to generate a However, there is this Code Spell Checker VS Code extension that works locally. It doesn't seem to have a CLI to integrate with CI, so might not be the silver bullet solution. I installed it locally with this {
"caseSensitive": true,
"words": [
"GitLab",
"gitlab"
],
"flagWords": [
"Gitlab"
]
}...and this is how it highlights in my IDE:
There is also this markdown-spellcheck npm package that might help with CI. Regardless, it's worth discussing. Do you want me to create an issue and continue the discussion there or do you want to take the discussion internally first? |
|
To add to my previous comment... Although not as much, using "Gitlab" instead of "GitLab" is just as silly as these:
We are engineers; of course we can write tools and linters to catch all different types of mistakes in all different file types, but would it be worth the effort and cost? Maybe just a "style guide" would suffice? Not as comprehensive, but something similar to these in a Markdown file:
Contributors and, more importantly, code reviewers would have a reference for common mistakes/inconsistencies:
Although I have a feeling that even a style guide wouldn't be the right place for wrong brand names... What would we put there? "Use brand names as they are; don't butcher them"? Isn't that inherent/obvious? |
We actually have an existing style guide, but are on the cusp of replacing it with a better and more cohesive style guide right now! We will be publishing our new style guide soon, so please hold tight in the meantime!
The examples you listed actually all have related rules that we have established in our existing style guide:
I don't believe we have a clear cut rule for brand names, but I agree that by default folks should use the capitalization the company themselves use. However, everyone makes mistakes, and I myself have been guilty of writing "Github" instead of "GitHub". The most important thing in documentation is clarity, not being perfectly right all the time. And I say that as a technical writer! 😂 |
hsnabszhdn
force-pushed
the
fix-gitlab-brand-name
branch
from
89a0cd0 to
9785a11
Compare
The actual brand is "GitLab" as opposed to "Gitlab":