How to be content with content: a guide to writing for Design Systems
Attention digital marketing writers/UX writers/technical writers! Have you spent your happy days writing product descriptions, promotional emails, or button copy—and suddenly someone has asked you to write for a design system? Maybe you smiled nervously and said, “Yeah, sure, I can do that. Absolutely. You betcha.”
Well, don’t worry. With a bit of context and direction, good writers can write anything.
So, uh, what’s a design system, exactly? A design system is... well, it’s a lot. Created to standardize the design and development of an organization’s digital experiences, a design system is made up of a component library, design principles, documentation, and more. It governs the design language of the brand experience, including—but not limited to—the colours, typography, and overall voice and tone. Learn more about design systems.
From a writer’s perspective, all of the components (e.g. buttons, dropdowns, etc.) need to be documented, the design language needs to be addressed in detail, and let’s face it: those design principles aren’t going to write themselves.
Who are we writing for? For the most part, the readers of design system documentation are software developers/engineers, and visual and/or UX designers, with a secondary audience of content and UX writers, marketing teams, product managers, QAs, and company executives.
Oh, and maybe the oh-so-nosy general public, too—many design systems are online for everyone to see.
What content should we include? Most design system content falls into one of three categories:
- Design principles: InVision says design principles are “a set of values that act as a compass for your product. They’re an agreed upon truth: the guideposts that keep your entire team on the same path as you move through the design process.”
- Styles: These are the rules for colours, typography, grids, motion, voice and tone, and other elements. Hex codes and pixels and line heights—oh my!
- Components: For each of these building blocks, it’s good to include a main description and variations; do’s and don’ts for design, development, content and accessibility; code snippets; a props table; a list of related components; and a section for additional resources.
As an added bonus, you should consider future contributors to the design, development or content of the design system, so you’ll be writing all about creating/designing/documenting new components. Or, say, a blog post on how to write for design systems.
If you’re working for an organization that has content teams integrated into the design and development process, it’s also valuable to have brand voice and tone guides, an SEO writing guide, a style sheet, and recipes for the layout of different pages, such as product pages.
How do we design and write this content? First of all, let your curiosity lead you and check out what others are doing. After a little competitive analysis, start the conversation within your organization about the kinds of documentation your development, design, QA, content, marketing, and other colleagues need. Need ideas on how to get this info? Host a workshop or send out a short survey.
Next (or at the same time), work with your UX and design team to be a part of the page layout discussions. Good content for documentation is consistent, clear, useful and honest, so make the case for those writing principles in the content design of the pages. In addition to other considerations, this means content should be chunked in such a way as to be scannable and in a format that is predictable and organic.
Note: Please be sure to design and write with accessibility in mind. As much as possible, content should be in plain English, and contain clearly written links (e.g. no “Click Here,” or references on the page to “see above,” or “look below,” etc.). Check out this Vox Media checklist for content writers to get into the accessibility mindset.
And, hey... when documenting components, you’ll have to address accessibility requirements, while also writing that content in an accessible way. META MOMENT #2.
Now it’s time to get into a room with your subject matter experts and start asking questions. Ask the developers and designers who are building the design system, and the QAs who are testing it, how the components behave: is there a parent component that governs the behaviour of this one? Can buttons be used to take a user to another page or is that exclusively a function of text links? Do the components that go on a product page have to be listed in a particular order so the screen reader can read it out?
If it seems a bit daunting to go in with a blank slate, you can ask your SMEs to do a “brain dump” into a document and then use that as a basis for pair writing sessions. After that, it’s time to edit, revise, and rewrite.
Keep in mind that overall voice in this documentation should stay consistent—and on brand—but that the tone can shift, depending on the topic and audience. Have discussions with your SMEs about who you’re speaking to, and find out whether, for example, designers need to understand the component properties or if that’s a conversation that developers have with other developers. Write that section accordingly, or, depending on the component, accordion-gly.
The users of this design system are going to have different objectives for reading this documentation—a designer may just want to make a decision about which component to use, while a developer might need to grab some model code—but keep in mind that the overall objective for the writing here is to inform, not persuade or direct.
What’s next? In an ideal world, we’d now refine the content with some feedback from quantitative and qualitative testing. It’s helpful to see how many people are consulting the documentation, where they’re focussing on when they’re on the page, and if/when they’re exiting. Something as simple as a three-question survey could really help put your content in perspective: Did you find what you were looking for? Was it where you expected it to be? Was it easy to understand?
Making the shift from writing technical, marketing, or UX-focused material to writing content for informational purposes can be a bit daunting, but it’s a fun and worthwhile challenge. Explore other design systems, talk to your colleagues, and stay curious.