[Meta] Strengthening the use-case-first framing

[LeaVerou]

The problem

A recurring piece of feedback when reviewing guides is "this is centered around a feature, not a use case." For a while I wondered if I just had the vision wrong — but @atopal and @rviscomi have consistently assured me that no, the vision has always been that MWG maps use cases → features, not the other way around.

As the ancient UX proverb goes:

If one user gets it wrong, it might be them. If multiple users get it wrong, it's definitely you.

So I've come to think that the way the project is structured pushes everyone toward feature-first framing, even though we want use-case-first. We first add features, then draft guides around them — which naturally forces a feature → use case mindset. But the problems you find starting from a solution and working backwards are not the same problems you find starting from a use case. We're basically trying to reverse-engineer the use cases!

This isn't a vibe, the architecture encodes it at every step. For example:

• The canonical workflow says so. CONTEXT.md, Stage 1: "Identifying use cases — Translate a web platform feature into distinct use cases." The documented pipeline's very first step is feature → use case.
• Use cases are children of features in the tracker. The new-use-case issues are auto-generated from guide.md frontmatter keyed on web-feature-ids, and their priority (P1–P4) is inherited from the feature. There is no first-class way to represent a use case that doesn't yet have a feature, nor to assign a priority to it.
• Features are the default axis. gd audit groups by feature; --usecases is the opt-in flag.

The result is that it's currently too complicated to propose a use case without also specifying its features. I have a backlog of use cases to propose, but filing issues for them means fighting the automation (see #974 for what happens if you try to use new-use-case without following the template).

The distinction I think we're missing

I'm not proposing we stop tracking feature coverage. It's the KPI, the eval harness measures it, and that's correct.

What I'm proposing is that we decouple the axis we measure on (features) from the axis we author and organize on (use cases).
Today those are the same axis, with features as the parent. If we separate them — organize freely by use case, and keep feature coverage as a test rather than a hierarchy — I think the "feature-first" complaint largely dissolves on its own.

Below is a diagnosis I'd love to get consensus on, followed by three proposals, each standalone and each with concrete asks.

Proposals

1. Decouple features from use cases

Adding a use case should be feature-agnostic. If you already know the relevant features, great. If you don't, that should be fine too. IMO the bar should be:

1. Is this a prominent enough use case?
2. Could agents address it better if they could fully utilize modern web features?

For most nontrivial use cases, (2) is almost always "yes." It's even defensible to admit use cases that pass (1) regardless of (2), because the answer to (2) constantly changes as agents, the platform, and our understanding of both evolve.
Example: the complex-shapes guide uses masking today. We may want to update it for corner-shape, then later border-shape. The feature set churns; the prominent use case is stable. We should anchor on the stable thing — which is the original vision, right?

Proposal: organize guides freely by use case, and treat feature coverage as a test: tooling verifies each feature we care about is covered by some number of guides, without mandating a parent/child relationship between them.

Ask: Can we agree the use case is the organizing unit, and feature coverage becomes a check rather than a hierarchy? If yes, I can prototype the coverage test.

2. Reduce requirements for stub/draft guides

Figuring out what use cases to cover is a fundamentally different activity from implementing the guidance for them — it can even be done by different people. But today the minimum to propose one is a guide.md stub with metadata (name, description, web-features) plus a demo file.

Suppose I want to log that we should have a guide for tabbed UIs. Writing a perfect demo tabs component takes orders of magnitude more effort than logging "we need a guide for tabs." I might write the guide anyway — but that shouldn't gate recording the need for it. Even figuring out which web-features are relevant is not always straightforward. E.g. a tabs component can use scroll-snap for scrolling the tabs when they don't all fit, or it could use popover to show a dropdown of the hidden tabs, but it's not a primary use case for either and it's normal if they don't immediately come to mind when thinking about the use case.

Recommendations (these are all independent so any or all can be implemented):

• Lift the demo.html requirement for guides that are stubs (PR submitted: fix(tooling): accept a guide.md stub without demo.html as a use case proposal #994)
• Lift the web-features requirement for guides that are stubs
• Consider any guide without web-features or a demo.html a stub instead of matching on its content. That way guides can be written and collaborated on and essentially be in draft status until all the bits are in place instead of considering this an authoring mistake. Alternatively, introduce a draft: true descriptor that skips checks.
• Introduce a "Needs Demo" state so this can become part of the process, not a gating function.

3. Make proposing use cases lightweight

Even setting the requirements aside, a PR is too heavyweight as an intake mechanism. It forces you to think veeery carefully because it creates real work for others — review, attention, resources. And people don't open PRs for things they're unsure have consensus, so with no lightweight way to gauge consensus first¹, in practice the ideas just… don't get filed. Sometimes that self-filtering is desirable; here it isn't. We want to cast a wide net and capture as many candidate use cases as possible, right?

Recommendation: one of:

• GitHub Discussions (with upvotes). It lets us gauge consensus, allows discussion, and is separate from issues.
• A dedicated use-case-idea label on issues if we'd rather keep everything here.

4. Make feature guides first-class — to absorb feature-centric content

This sounds like it contradicts everything above, so bear with me. We already have features/*.md, but we only use them for transclusion and have resisted treating them as real guides. The usual objections — "isn't that MDN's job?", "if the agent knows the feature, it can search" — are fair.

But the point of first-class feature guides isn't just what they add, it's what they remove. Today, because feature guides aren't a real concept, feature-centric content has nowhere to live except inside use-case guides — so use-case guides keep drifting into being feature guides in disguise (when all you have is a hammer, etc.). Give that content its own home, and the use-case guides are freed to actually be about use cases. Better still, once a feature guide for X exists, any use-case guide that drifts too close to that invites the obvious question: "what does this add over the feature guide?" — a clean rule-of-thumb for inclusion.

And crucially: this content already exists, and it's already the right shape — hyper-condensed, and optimized for this purpose. That's a different artifact than "go read MDN." or even "use the MDN MCP server". Yes, it could live elsewhere one day; today it lives here.

Ask: Can we sanction features/*.md as publishable feature guides in their own right, not just transclusion sources? (related: #743)

---

Happy to flesh out any of these further if they have @rviscomi's blessing!

The one thing I'd most like consensus on first is the diagnosis — that measuring on features and organizing on features are two different decisions, and we've been making them as one.

Footnotes

1. Why might there not be consensus? Many reasons! E.g. maybe the use case is too niche. Maybe it's not really a use case. Maybe an existing guide already covers it or should. Etc etc. ↩

[captainbrosset]

Figuring out what use cases to cover is a fundamentally different activity from implementing the guidance for them — it can even be done by different people. But today the minimum to propose one is a guide.md stub with metadata plus a demo file.

Suppose I want to log that we should have a guide for tabbed UIs. Writing a perfect demo tabs component takes orders of magnitude more effort than logging "we need a guide for tabs." I might write the guide anyway — but that shouldn't gate recording the need for it.

Even setting the demo aside, a PR is too heavyweight as an intake mechanism. It forces you to think veeery carefully because it creates real work for others — review, attention, resources. And people don't open PRs for things they're unsure have consensus, so with no lightweight way to gauge consensus first1, in practice the ideas just… don't get filed. Sometimes that self-filtering is desirable; here it isn't. We want to cast a wide net and capture as many candidate use cases as possible, right?

I agree and would go as far saying that it'd be great to go look for use cases where they currently exist rather than create another place for people to submit them. Unless you're suggesting that the discussions is where we'd paste use cases found elsewhere.

One idea is the WebDX's developer-signals repo where developers are already telling us about their use cases. And here is a file that maps these use cases to features https://github.com/web-platform-dx/web-features-mappings/blob/main/mappings/use-cases.json.

[LeaVerou]

I agree and would go as far saying that it'd be great to go look for use cases where they currently exist rather than create another place for people to submit them. Unless you're suggesting that the discussions is where we'd paste use cases found elsewhere.

One idea is the WebDX's developer-signals repo where developers are already telling us about their use cases. And here is a file that maps these use cases to features web-platform-dx/web-features-mappings@main/mappings/use-cases.json.

I generally agree, though I think use cases found elsewhere would need some curation. The use-cases.json file you linked to is a great example: lots of great data there to devour, but we can't just 1-1 map these to guides.

• Some might be too niche as worded
• Some might be served fine by agents already
• For some we have guides already
• etc

I do think we should go through them and they'll probably generate a lot good missing guides. It's just not as straightforward as converting every single one to a missing guide issue.

But I fully agree on the big picture point that we need to proactively dig up use cases in their natural habitat.

On a similar vein, I'm going through popular design systems and cataloguing common components and which ones are use cases that we should have guides for.

The thing is, right now we don't really have a good way even for ourselves to propose these and discuss them! The most minimal process is to open a PR with a dummy demo.html.

---

Discussed this with @rviscomi in a call today. His view was:

1. We need both feature → use case and use case → feature processes
2. Fully agreed that we need a more lightweight process to propose use cases
3. He was unconvinced wrt exposing feature guidance as guides for now, but was open to re-evaluating later.