Contractor: How to describe features defined for instances, groups, and projects
Problem to solve
2025 update
The current docs guidance advises against using "level": https://docs.gitlab.com/development/documentation/styleguide/word_list/#level
The docs use the word "level" in many different ways. Some examples:
- project level
- group level
- instance level
- cluster level
- chart level
- access level
- permission level
- visibility level
- top-level directory
- third-level heading
- the customer's level of flexibility
- the top-level interface
- level of uptime
While "level" can be helpful to express that things build on other things, if you are a new user and you don't understand the "levels," you might be confused. We should strive to be as specific as possible.
Side note: During a Runner meeting, we noticed that some teams are using different icons/indicators for features defined for the instance, group, and project, so we should probably sync with UX on icons/usage.
Proposal
I'd like to remove the word "level" as much as possible. When a feature is defined for the instance, group, or project, we can use language like, "For the instance, ..." or "For the project or group, ..."
Here are some example re-writes, pulled straight from the docs.
Example 1:
- Now:
The total number of instance level CI/CD variables is limited at the instance level. - Proposed:
For your instance, the total number of CI/CD variables you can use is limited.
Example 2:
- Now:
To preserve group-level relationships from imported projects, run Group Import/Export first, to allow project imports into the desired group structure. - Proposed:
To preserve group relationships from imported projects, run Group Import/Export first, to allow project imports into the desired group structure.
Example 3:
- Now:
Use instance-level or group-level default settings for a project integration - Proposed:
For the instance or group, use default settings for a project integration