Photo by Maarten van den Heuvel on Unsplash

Authoring Good Design Documentation

Good documentation is vital and shows that you care about your design system and those who will use it. Lacking good documentation practices could spell doom for a design system.

Documentation is debt

  • Open for us to read and change—a question of policy and access
  • Easy to write and update—a question of adequate tooling
  • Ideally, covered by the same work cycle that covers the relevant practical production part
  • Respected in your organization

Tip: Don’t share the same format or assumptions for tactical, short-term (“volatile”) docs as for strategic documents

Learn from the past; don’t repeat it

Documentation can be both formal and informal

Informal work

  • Pages, whose order and naming also could be seen as a kind of “architecture” or taxonomy of how we divide up design
  • Annotations and redlines to communicate details that may be non-visual
  • Figmagic-compliant elements/components should have an internal structure that make them easy to understand and translate into code
  • Constantly cleaning up and structuring layers, groups, etc.
  • Using Figma styles and design tokens to be explicit about atomic design decisions

Screaming architecture

Screaming architecture, in the real (physical) world
Screaming architecture, in the real (physical) world

Your architectures should tell readers about the system, not about the frameworks you used in your system.

Screaming architecture, in our component library codebase
Screaming architecture, in our component library codebase

Self-documenting and self-evident always wins

  • Give everyone skin in the game, so they are co-responsible for their work. If it’s expected that everyone documents, then it’s no longer a single-player game, and the aggregate quality should rise because, as with everything: what you do a lot, you get good at.
  • Make it easy to do the right thing. Provide access to docs to everyone, co-locate docs with code or other work materials, and require that all work is documented at the required level: sometimes nothing, sometimes a lot.
  • Sometimes docs are not the answer. Onboarding new members into soft values and explaining the rationale of decisions to stakeholders and why we work the way we do can do more to create a strong group than docs over-rationalizing every last bit.



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Mikael Vesavuori

Cloud Software Architect (and Technical Standards Lead) at Polestar