Contractor: How to describe features defined for instances, groups, and projects
Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.
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