[msum]

This article aligns with a lot of my person experience. I'd add a few of my own observations on design systems:

1. The team making the design system needs to be really passionate about making a design system specifically

2. Everyone on the design system (DS) team needs to be pretty far in their careers, and have a few failed or quasi-successful attempts in their past experience.

3. Everyone's skills should overlap but each individual should bring their own depth/area of expertise.

4. I've never seen a "contributing back" model work, really. There can be some collaboration, or specific asks, but when you have a really cohesive DS team, they took the time to become that cohesive and it shows.

5. No matter how good the docs are, there will always be people who don't read the docs. I'm tempted to go as far as to say that I think there should be an onboarding course on how to use the design system that teams have to take before they can use it. (I legit don't know how else to reasonably solve this issue).

6. Make it compliant with accessibility requirements (at least bare minimum WCAG Success Criteria). I've seen that alone drive adoption for design systems.

I've been creating for web for 25+ years now, and I've only seen 1 or 2 successful design systems. It's so easy to get it completely wrong, or get off track.

[SamoyedFurFluff]

On a point 5, never underestimate the amount of labor someone is willing to undergo in order not to learn something. Educators everywhere share your struggle!

[Perz1val]

You should also take into consideration that reading docs takes time. If a different designer (marketing guy) is supposed to do a simple 30m task (draft that Merry Christmas popup real quick), they probably won't get those extra 5 hours to read the docs

[suzzer99]

And after those 5 hours you spend another 5 hours beating your head against the wall until you finally realize the docs are out of date.

Stale docs are worse than no docs. IME (at non-FAANG, non-tech darling companies) docs *always* go stale pretty quickly. No one wants to take on the thankless, unbudgeted task of keeping the docs up-to-date, or browbeating all the other devs to update the docs when they make changes.

The only docs I push for are stuff like swagger where the documentation is also living code. Otherwise I say just put it in the readme, and every repo has a clear owner responsible for keeping that readme up-to-date as necessary.

[locuscoeruleus]

I think this is an expectation thing. People expect to be able to figure it out in time x. They expect they'd have to use y time to find the solution in the docs. And people will most often estimate that x <<< y, having been burned by bad documentation before. People will often be disappointed that their search through the docs didn't get them any answers and most people will have strong memories of "figuring it out eventually" by throwing spaghetti at the wall long enough.

[marcos100]

I believe the future will be to feed all your docs into a LLM for people to query.