Writing for design systems

Creating effective, actionable documentation.

Challenge

I joined Infor to help their design system better communicate its intent. The documentation had grown to support over 100 components across 3 code frameworks and had become siloed between design and dev.

Much of the docs were geared toward describing the values and specs that were built into components, but the “how” and “why” of using them wasn’t always clear.

I noticed more themes that design system teams commonly struggle with:

• delivering a unified, consistent perspective to users, when there are multiple contributors
• communicating flexibility while still promoting system reusability
• defining what a system should (and shouldn’t) document
• organizing info among design and development disciplines

How I helped

Authoring style

I developed documentation principles to define success for the project and give contributors a sense of what effective docs looked like. I used those to create a basic technical writing style guide that helped contributors (and myself!) author content in a way that sounded cohesive in the docs.

Component template

To standardize component usage, I designed a scalable template that could align design and dev usage for any component.

Iterating on the template with feedback from users and stakeholders, I reached a scalable model that worked for both basic and complex components.

AI style recs

To make it easier to implement the style guide and usage template, I created a custom GPT that team members could use to get recommendations on our authoring style or generate boilerplate component best practices.

Demo:

Writing for design systems Jake Klocksien