Every month I run a free Zoom session called Design Systems Open Space.
It’s for people who work on design systems to come together, meet each other, and talk about anything we’re grappling with.
Each month we focus on a different topic - and January’s open space covered my all-time favourite design systems subject: documentation.
Here are my reflections from the session.
Design systems documentation is a team sport
The very first question that came up was one of ownership: whose responsibility is it to write documentation?
With content designers and tech writers still a rare breed in design systems teams, many lack a dedicated person to take this on. But is that a bad thing?
Whilst I absolutely advocate having a content specialist working on your docs, good documentation is never the work of one person. Designers, engineers, researchers and product managers have valuable and varied perspectives to guide the information we provide to our users.
So the task is not simply to hire a dedicated documentation person, but rather to empower multi-disciplinary team members and contributors to document their own work effectively and collaboratively. In my experience, this is best achieved through the provision of standard templates and formats, skills training, peer review, and testing.
One attendee spoke about their efforts to create standard, reusable formats to support people writing documentation. Whilst this had helped to some extent, they admitted that the templates could sometimes be overly constraining. And, in my view, this is where we need to get meta.
If we’re providing reusable templates for documentation, it’s helpful to consider them as design patterns. There will be cases for contextual adaptation, so we need to document our documentation in such a way that makes clear this is OK - that the template is a guide, not a law.
Maintainability is important to consider - and often overlooked
More than one attendee shared experiences of investing significant time and energy into documentation that ended up unread, outdated and - in one instance - never published.
This had left the authors feeling understandably frustrated and guilty. And it’s a common scenario.
When creating documentation - and indeed any aspect of a design system - it’s important to be realistic about what you and your team can maintain. Tempting as it is to go straight in with comprehensive solutions seen in other, mature design systems, it’s much better to start with minimum viable documentation and build on it over time, as team size and capacity increases.
Good documentation meets people where they are
I was pleased when the discussion veered onto my current documentation obsession du jour: managing documentation across multiple tools.
While the majority of us still take a fairly unimaginative approach to the placement of our documentation - with the bulk of it still living in a dedicated docs site - there is an emerging shift towards documentation that meets people where they are.
For designers, for example, this might mean surfacing guidance alongside components in a tool like Figma, and developers might be best served in something like Storybook or GitHub.
The big challenge we have today is how to achieve this in a way that’s maintainable. Publishing documentation to multiple places, with no system for managing it centrally, creates a significant overhead that most design system teams simply do not have the capacity to sustain.
I’ve written about this problem previously:
- We document our design systems, so why don’t we systematise our docs?
- Design systems and structured content
To my knowledge, answers to this problem remain incomplete and thin on the ground, so I was excited when one participant shared that they’d been working on a custom tool that might be able to support this. I’ll be keeping a close eye on their progress.
Measuring the performance of our documentation
Another oft-overlooked aspect of design systems documentation is how to measure its performance over time. Whilst many of us strive to track generic system metrics like component usage, contribution, and user satisfaction - only a minority seem to actively monitor the efficacy of documentation.
One attendee recommended looking to support requests as a source of insight into how far our documentation is meeting people’s needs. It reminded me of a system we established during my time on the GOV.UK Design System team, where we’d tag our docs-related support tickets by issue type (for example: couldn’t find; doesn’t exist; didn’t understand), and topic (for example: component; contribution; installation).
We’d track the quantity of different query types and keywords, and review each month to find areas for improvement.
This helped us prioritise improvements to our documentation based on user needs, and use “reduced support requests” as a metric to help us measure the efficacy of any changes we made.
Design systems documentation is absolutely critical - and hard to get right
I was heartened that no one questioned the need for good documentation during the discussion (I’m sad to say that it does happen).
But this topic, more than any other that we’ve discussed in the open space sessions, seems to present real challenges.
One participant remarked “Documentation gives me the most imposter syndrome of any of these topics.”
And this, I think, is because good documentation is hard to get right. It’s easy to look at unread documentation and assume that our design system’s users have a generic aversion to reading - that they just want to grab components and go, ungratefully eschewing all of our carefully-crafted guidance.
More often than not, it’s because our documentation is failing to give them what they need. When we provide people with too much or too little information, fail to address their particular context or skillset, or our documentation is poorly named and signposted, they’ll naturally circumvent our guidance in favour of approaching us directly.
In short, they’ll take the path of least resistance.
Learn how to write design systems documentation that works
If you’ll forgive me a little plug, this is where I think I can help. I’ve spent the past 7 years helping teams create and refine design systems documentation that people can find, understand and use.
I understand the challenges people face when writing documentation, and I truly believe that learning to do it well is the most transformative step we can take to improve our design systems.
So in a few weeks’ time I’m running 2 half-day training sessions on writing design systems documentation:
- Writing design systems documentation training, 8 Feb
- Writing design systems documentation training, 15 Feb
There are just a few spots left now, and I’d love to have you along if you can make it.
If you have any questions, you can get in touch on Twitter, Mastodon, or email me on amy.l.hupe@gmail.com.