Draft: feat(FeatureDiscovery): rewrite feature discovery

Closing this MR 2024-10-02

Closing this MR as it's too large, I've created a smaller MR and documented a rough plan of MRs.

What does this MR do?

My pain points with the current guidelines:

• Each time I add feature discovery, I don't know what UI element to choose or what's "allowed", e.g. "can I show a popover without user action?"
• 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:

• 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.
• Guidelines are more actionable and concrete

Exploration to date

I tried to explore this by reading external research, other work done at GitLab, collating patterns from other products, and even running some small scale testing to investigate the impact of CTA position and style of feature discovery mechanism. (I question the validity of small scale testing due to the small sample size.)

Status & feedback requested

I don't not expect this MR to actually be merged. I figured it's easier to start a discussion with a rough draft of a proposal, and after discussion, I can break up the changes to smaller MRs.

This MR misses some crucial information like:

• How feature discovery ties into first onboarding
• Feature discovery for upsell features - e.g. "upgrade your tier..."
• Probably more

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.

Links