feat(FeatureDiscovery): reword guidance to decision tree
Background context
This MR is the first in a series to rework feature discovery guidance. This MR is a follow-up to this research issue and this draft MR.
What does this MR do?
Rewords feature discovery guidance to be more of a ranked decision making framework. Makes guidance a bit more opinionated.
Problem to solve
- Designing feature discovery is manual effort each time, lots of individual decision making on the designer.
- I don't know what pattern most effective or appropriate for my use case.
- We are quite inconsistent how we handle feature discovery.
- GitLab has a tendency to show many banners and loud notices, difficult to argue against adding a banner with current guidance.
Goal of this MR
- Guidelines are more ranked guidance, with a lot of emphasis on making sure the feature is in the right place in the user's workflow.
- Discourage disruptive feature discovery guidance without justification.
- Guidelines are more actionable and concrete, provide use case examples per pattern.
After this MR
Known issue
This MR does not touch the existing Onboarding content on this page, to keep the changes small. That content slightly conflicts with the changes in this MR, or at least isn't harmonious. I would rather tackle cleaning that up in a follow-up MR.
Other follow-ups
This MR is intentionally kept "small", but there's a lot more I intend to add in follow-up MRs, detailed in this plan.
Does this MR meet the acceptance criteria?
-
The MR title and commit messages meet the Pajamas commit conventions. -
The “What does this MR do?” section in the MR description is filled out, explaining the reasons for and scope of the proposed changes, per “Say why not just what”. - For example, if the MR is focused on usage guidelines, addressing accessibility challenges could be added in a separate MR.
-
Relevant label(s) are applied to the MR. -
The MR is added to a milestone. -
If creating a new component page from scratch, it follows the page template structure. -
Content follows the Pajamas voice and tone guidelines, falling back on the GitLab Documentation Style Guide when needed. -
Related pages are cross-linked, where helpful. Component pages have related components and patterns defined in their Markdown front matter. -
If embedding a Figma file, it follows the Figma embed guide. -
Review requested from any GitLab designer or directly from a maintainer or trainee maintainer. -
Maintainer review follows the Pajamas UX maintainer review checklist.