Document the navigation approval process in handbook and Pajamas
Problem
Right now, our approval process for Navigation has instructions in two places:
-
Pajamas
- Currently has some rules around the process
-
Navigation in the handbook
- Links to navigation change issue template
- Outlines process
Proposal
-
Make Pajamas the place for describing the design pattern -
Make handbook the place for describing the process -
Consider adding the process to docs as well and a link to both -
Create a new issue template: Update navigation proposal template (gitlab-org/gitlab!114207 - merged) -
Create MRs to update -
Consider adding a link from our docs to this information so it is readily available.
✍ Handbook content:
Note: This will be an MR to this page: https://design.gitlab.com/patterns/navigation
The process for merging a navigation update:
- Review the current rules around navigation submissions
- Start an issue with this template - see how to make a great proposal below
- Tag Foundations PM early (Christen) on your implementation before scheduling your issue
- Get approval from the Foundations PM on your MR
- Build your nav item according to {{docs}} - Sam will maybe create this
- The navigation team needs to update the DBT model with your new item
- Final merge will be via the a Foundations FE team who are CODEOWNERS
- Merge
Current navigation rules
- Putting a feature behind a feature flag is not exemption for this process
- We don’t add items for the sake of discovery
- Use project organization as a basic expectation for introducing something to the group.
- We are actively fighting feature bloat. Imagine GitLab had 500 nav items. This would get unruly fast.
-
From Pajamas
We do not add newtop-levelmenu items in order 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 to make a great proposal
Steps to get a change merged into the navigation:
- Start with crafting a vision. Start with how it might look in the first MVC and where you hope to be one day, even if it doesn’t pan out to be accurate. - This can be a direction page or mockup. Whatever helps show how you imagine this being inside of GitLab.
- Engage tech writing. They can help craft a term that best describes the feature(s) you’re proposing
- Some things to consider:
- Not every page should be its own nav item. Is it possible to integrate into an existing page? Think Locked Files and Repository. We want to avoid this in the future. Consider configuration or settings pages and tabs.
- Show us one other place besides navigation that you considered
- Link to any business case info for this. For example is it a new category, will it drive revenue?
- If using an existing grouping, talk with the other tenants to see if it corresponds with the other features there. We didn't do a great job of this before. For example, Environments are more often used with CI/CD but it’s currently separated.
- We don’t optimize for the future. Think it’s okay to share rooms with a sibling when you’re under 10 years old, but we aren’t going to give you your own room until you’ve grown up.
- Validate the riskiest assumptions around placement with user research. Read the guidelines on how to test in the handbook.
📰 Issue template
<!-- This template is used for proposing changes to the navigation. This could include additions, removals, or general changes to overall hierarchy.-->
### Proposal
<!-- Use this section to explain the proposed changes, including details around usage and business drivers. -->
### Checklist
- [ ] Add relevant information to the issue description detailing your proposal, including usage and business drivers.
- [ ] Ensure your UI suggestion align with the [Documentation Style Guide](https://docs.gitlab.com/ee/development/documentation/styleguide/)
- [ ] Engage ~"Technical Writing". They can help craft a term that best describes the feature(s) you’re proposing.
- [ ] Follow the [product development workflow](https://about.gitlab.com/handbook/product-development-flow/#validation-phase-2-problem-validation) validation process to ensure you are solving a well understood problem and that the proposed change is understandable and non-disruptive to users. Navigation-specific research is mandatory for additions or when restructuring.
- [ ] Engage the [Foundations Product Manager](https://about.gitlab.com/handbook/product/categories/#foundations-group) for approval. The Foundations DRI (@cdybenko) will work with UX partners in product design, research, and technical writing, as applicable.
- [ ] Consider whether you need to [communicate the change somehow](https://design.gitlab.com/patterns/navigation#messaging-changes-to-users), or if you will have an interim period in the UI where your item will live in more than one place.
- [ ] Ensure engineers are familiar with the [implementation steps for navigation](https://docs.gitlab.com/ee/development/navigation_sidebar.html#navigation-sidebar).
/label ~UX ~"UI text" ~"documentation" ~"Category:Navigation & Settings" ~navigation ~"workflow::problem validation"
✍ Pajamas content:
Note: This will be an MR to this page: https://design.gitlab.com/patterns/navigation
- Remove process focused content
- Remove dead links
- Start adding documentation for the new navigation
Edited by Austin Regnery