Style guide for access, permission, role names and its usage unclear

[janbrasna]

Code of Conduct

• I have read and agree to the GitHub Docs project's Code of Conduct

What article on docs.github.com is affected?

https://docs.github.com/en/contributing/style-guide-and-content-model/style-guide#permissions

What part(s) of the article would you like to see updated?

The chapter defines role usage in caps & quoted:

Resources (e.g., "Write" for a repository, "Admin" for a security advisory)

yet the examples below don't use any of that:

Avoid: People with the write role can...

Trying to follow the Style guide, I'd be tempted to use:

Avoid: People with "Write" role can...

Is there a clear style to follow? I'd like to adhere in PRs as much as possible.

Additional information

• In Quote role names in rulesets #31532 I've proposed some quotation to make the sentence more clear that it refers to "token" words as roles.
• I've followed the Style guide https://docs.github.com/en/contributing/style-guide-and-content-model/style-guide#permissions where it shows the resource role as quoted and capitalized.
• However the same style is not followed in the examples right after the definition, so I'm opening this issue to clarify the usage, and eventually fix the examples or the definition to start with.

[nguyenalex836]

@janbrasna Thank you for opening this issue, as well as providing additional context on this issue alongside the other PR you opened! ✨ I'll get this triaged for review 💛

[github-actions]

Thanks for opening an issue! We've triaged this issue for technical review by a subject matter expert 👀

[ethanpalm]

Hi @janbrasna, thanks for asking this question and opening an issue to clear up this confusing part of the style guide.

The definition is misleading here and the terms should not be capitalized or use quotation marks. The examples like

People with write access can

are the proper style.

I reviewed the rest of the style guide to make sure that there aren't other examples like this that use quotation marks to introduce terms that don't need them and it looks like this is the only one. Removing the quotation marks and making the terms lower case in the permissions section should make this more clear 😄 .

You or anyone else is welcome to open a pull request to make these changes!

[janbrasna]

@ethanpalm Thanks for the info. I'll look into it, just need a bit guidance here if possible:

1. I've seen occurrences of "people with the write access" which sounds weird — this should be probably mentioned in the examples to avoid?

2. I originally came from Quote role names in rulesets #31532 where the sentence in question felt weird (to me, probably as a non–native speaker):

   "The following are eligible for bypass access: - The maintain or write role, or custom repository roles based on the write role"

   so just checking this wording is correct. (No problem with "with whatever access", just the analogous "the foo or bar role" sounded puzzling. Maybe the definite article here is the culprit? Should the sentences about roles be reworded like "People with maintain or write roles,…" to get rid of the article? — Sorry I suck in English so might need a little more hand-holding fixing this than a proper content person would need;)

Also relevant from Style guide and content model: https://docs.github.com/en/contributing/style-guide-and-content-model/contents-of-a-github-docs-article#how-to-write-a-permissions-statement

[gsosm0760]

Emeğinize sağlık