GitLab Navigation

The group::foundations team owns the navigation structures of the GitLab product. Please review this information if you plan to propose changes to GitLab navigation.

Note: a Code Owners approval rule is in place to prevent unapproved changes to the navigation. If you have not followed this process, your Merge Request will be blocked.

What is navigation?

Navigation refers to elements that aid users in moving around GitLab, which includes their organization and wayfinding clues. The navigation experience directly impacts the usability and discoverability of our features. This document describes how we can collectively evolve the navigation while still meeting our goals.

Why do we need to be careful when changing the navigation?

In the past, teams added items to highlight new features. However, this created an overwhelming navigation structure that makes it challenging for users to find what they need. Our quarterly GitLab SUS survey continues to highlight these recurring themes:

• The navigation is complex or confusing
• The navigation is difficult to learn
• The navigation is not intuitive

What kind of navigation changes require approval?

While GitLab’s UX allows users to navigate across the product in different ways, the focus of the approval process is on the left-side navigation. This area serves both as navigation and as a feature discovery point for users. As the navigation evolves, it’s crucial that we maintain a balance between a focus on core workflows and feature visibility.

To help maintain this balance, we ask for everyone to use this process when proposing changes to the left-side navigation:

• First, second, and third-level navigation additions
• Renaming a navigation item
• Removing a navigation item
• Changing the sort order of navigation items
• Changing navigation functionality or features
• Launching an Experiment or Beta feature
• Changing the viewership of a navigation item (e.g. moving from disabled by default to enabled by default)

When to change the navigation

We only make new additions to the GitLab navigation structure through a deliberate process that is intended to optimize user workflows. This video summarizes the main factors that are important to consider as we iterate on our navigation. In the past, teams added items to highlight new features. However, it becomes impossible to accommodate every new feature, as this creates an overwhelming navigation structure that makes it too difficult for users to find what they need to complete their tasks.

Therefore, we do not add new items to:

• Improve discoverability of new features. Instead, look for other opportunities to highlight the functionality throughout the product.
• Optimize for the potential future. We should be forward thinking without over optimizing. As features are developed and added, we can look into what changes may need to occur to support a growing feature.

How do I evaluate navigation changes?

There are two main questions we need to answer for navigation changes:

1. Does this navigation proposal facilitate one of our primary JTBDs? Which job?
2. How does this change improve the workflow for users attempting to complete that job?

There are many different types of Problem Validation research that could be done to learn about areas of opportunity for our navigation. The specific type of research performed should be based on the research questions and goals of the study. The following research methods and frameworks are some examples of ways research can be used to justify a new addition to the existing GitLab navigation:

1. Contextual inquiry: This method involves observing and interviewing users as they perform tasks related to their role to understand the “why” and the “how” behind them.
   • Example: Users may demonstrate how they navigate through multiple menus and pages in GitLab to find their dashboards. This insight would reveal the need for a single page in GitLab to find all dashboards.
2. Jobs to be Done (JTBD): This framework is a type of foundational research meant to learn the job(s) that customers want to accomplish within their roles. Jobs allow us to define the circumstances, goals, and outcomes of customers’ work.
   • Example: By interviewing users, we learn that have a main job of tracking metrics to show the health of their application, so they can identify when the application is failing. This insight would suggest a gap we could fill in GitLab by adding a page for displaying application metrics.
3. Diary study: This method is used to gain feedback from users over a period of time, so we can uncover changes that occur over days, weeks, or months.
   • Example: When gathing feedback about how users engage with a major change to GitLab’s navigation bar, we observe that GitLab admins continuously struggle from one month to the next with locating the admin area to adjust settings. This insight would suggest we need to surface the admin area in the user interface since it is not easy to find over time.

Questions to ask to learn whether a change to the navigation is needed:

1. What are the main tasks assocaiated with your current role?
2. Why are those tasks important? What would happen if you could not complete those tasks?
3. Show me how you perform a specific task using your existing tools.
4. What, if anything, would you improve about the process of completing that task?

After there is insight into a problem with the navigation, the Product team DRI should work with Product Design and UX Research to evaluate the ideal solution through a subsequent solution validation study.

How to propose a navigation change

If your primary goal is to improve discoverability of your feature, please start by looking for other opportunities to highlight the functionality throughout the product.

1. Before opening an issue, review the elements and patterns for navigation in Pajamas. It is worth checking the direction page to see how your proposal aligns or conflicts with upcoming changes.
2. Review the list of navigation changes and what they are to make sure your change qualifies.
3. The Product Manager for Foundations is the DRI for navigation changes. Reach out to them to determine whether your proposal needs full validation or limited validation.
4. You can initiate the review for this process by using the Navigation Proposal issue template.
5. Designers on Foundations will assist the DRI by reviewing the proposal and providing input. The typical turnaround time from the Foundations team will be 1 milestone. After providing feedback, it is the responsibility of the DRI to move the proposal forward and seek additional feedback as needed.
6. When you have approval and are ready to start implementation, then follow the GitLab Docs on adding items to the navigation.

Full validation path

This path is suitable for navigation changes that affect a majority of GitLab users or that introduce new design patterns. Some examples of changes that may need full validation are:

• Launching a Beta or Generally available feature
• Changes to navigation structure or functionality
• Removing an existing navigation item
• Renaming an existing navigation item

The Foundations PM is the DRI for determining if your proposal should follow the full validation path. On this path, we require the following steps be completed and documented as part of the navigation proposal issue.

Limited validation path

This path is suitable for navigation changes that affect a minority of users or that follow pre-existing design patterns. Some examples of changes that may need limited validation are:

• Experimental features available behind a feature flag
• New 3rd party integrations that follow the pattern of existing integrations
• Changes that bring consistency where there is already inconsistency

The Foundations PM is the DRI for determining if your proposal can follow the limited validation path. On this path, we require the following steps be completed and documented as part of the navigation proposal issue.

Reconciliation process

The navigation proposal process attempts to balance a focus on core workflows and feature visibility, which means sometimes proposal authors may disagree with the Foundations team decision. If you feel like we’ve struck the wrong balance, let’s follow the manager mention thread process. Add a comment to the proposal and:

1. Summarize why the proposal was rejected and your perspective on why this decision is incorrect
2. Mention your manager and the Foundations PM manager
3. Request their input on the decision

View page source - Edit this page - please contribute.