Define: What is a setting
Problem to solve
Pajamas has a dedicated page outlining the usability and interaction for settings management, but lacks specific guidelines for what exactly should be classified as a configurable option under settings.
Trying to read the Product Principles (deciding whether to add configuration) in tandem with Pajamas still doesn't answer where is the best place to put something in the product.
This ambiguity has lead to inconsistencies across the varying contexts of GitLab. Teams should be able to easily discern what is the correct placement.
Tasks
-
Define a hypothesis around what makes something a setting to aid decision making. -
Build a high level flow (See FigJam) to illustrate a potential change in the structure. -
Test the definition of settings and the flow against existing or proposed GitLab paradigms (See Figma) -
Propose a new page (Patterns / Settings) cross reference to sections in Product Principles
Draft: Hypothesis
Considerations: guidance to help make decisions.
- Generally, most pages in GitLab are not considered within the scope settings.
- It can help to ask yourself, would you or a user expect to find this item somewhere in a dedicated settings menu or elsewhere?
- GitLab objects like the Instance, Organization, Groups, Projects, and Users have a dedicated area to aggregate their settings together.
- Settings allow users to control how features or capabilities should behave or appear, and should rarely change.
- Settings are comprised of configurable options or attributes which present choices to the user to modify baseline functionality.
- Structure of settings is simple. Complex interactions served as an app are not a setting.
- Infrequent actions that are chores or maintenance related should be discoverable within a settings page.
Best practices: approaches that provide consistency and familiarity
- Users should be able to glance at settings and understand all the individual selections and effects.
- Allow users to modify task-specific options without going to a dedicated settings area.
- Following our configuration principle by limiting the number of options in settings.
- Show only what is relevant for decision making.
Draft: Examples
- Labels – not a setting, but rather a categorization tool
- Access tokens – not a setting, but rather a credential used for authentication and authorization.
- Variables – not a setting, but rather a reusable asset for CI/CD. Frequently utilized or referenced.
- Badges – a setting, since it contains options that can be configured. Rarely changed.
- Issue templates – a setting, since it contains options that can be configured. Rarely changed.
- Project name - a setting, since it is an option that can be configured. Rarely changed.
- Review apps - a settings, since it is a configuration option. Rarely changed.
- Clean up environment - not a setting, but a task done as a form of maintenance. Exception: List under configuration.
Checklist
Make sure the following are completed before closing the issue:
-
Assign the correct component label to this issue. -
Create an MR with the additions or updates needed. -
When introducing a major or breaking change, communicate the changes within the Engineering Week in Review and UX Weekly meeting. -
🎉 Congrats, you made it! You can now close this issue.
Edited by Austin Regnery