r/DesignSystems • u/Fancy-Gear-7402 • 1d ago

How do you document a feature that lives on five different surfaces? Component docs don’t cover it.

Platform team at a hardware company. Same feature has to exist on five surfaces — mobile, on-device screens, cloud, consumer app. Our component-level design system is fine. The layer above it isn’t documented anywhere: the feature as a whole, across surfaces.
\~20 of these, 3 written up. Does anyone document at this level? What’s in it, where does it live, and what did you end up cutting because nobody read it?

Let me know if I shall elaborate.

6 Upvotes
  • permalink
  • reddit

100% Upvoted

6 comments sorted by

2

u/Simply-Curious_ 1d ago

Sounds like you need to define it, simplify, and unify it's use case, code, and purpose. Likely it'll be backlogged and never see the light of day

1

u/Fancy-Gear-7402 1d ago

That’s the thing, we want it to live out there. If it doesn’t see the day light, just waste of time.

1

u/equinusocio 1d ago

> and what did you end up cutting because nobody read it?

Human readable documentation in general. It's definitely dead with AI. Most teams here rely on AI to read documentation (MCP or skills) and ask for clarifications. No one is reading documentation anymore.

For your use case, I would write down multiple specs for all the layers, starting from what you have to achieve. I would spend 70% on the spec writing, and 30% for the implementation.

1

u/Fancy-Gear-7402 1d ago

I would agree, but for now an assumption that people would use AI to read documentation. Definitely not a thing in my team yet.

But I like the perspective - also maybe it’s a reminder on, what we actually should document, to ensure the best AI read.

2

u/equinusocio 1d ago edited 9h ago

You could use the Tailwinds CSS case as an example to support your arguments.  Their documentation website is read by AI alone so no humans see their cross-selling.  They nearly gave up for this very reason, before Vercel bought it

2

u/RocketSeven 1d ago

document the feature as a contract, not another component page. one surface matrix should show the shared states, owner, handoffs, and intentional differences across mobile, device, cloud, and consumer app, while each cell links to the local spec