Over the last few years, here at Kyan we’ve experimented with a number of different approaches to documenting our design systems into living style guides and creating pattern or component libraries for our projects. It’s been something of a journey of discovery, and so far we’ve probably never quite hit on a solution that’s ticked all the boxes for us, even when we hand-rolled our own system for Rails!
So before we kicked off a large React project recently, I spent a little time upfront considering a few of the issues we’ve faced so far, to help us identify some key points to look for in a solution.
Pain Points
Among the sticking points we’ve encountered, are system flexibility and extensibility. Every project is different, so the ability to add or remove entire sections, or switch to a different taxonomy without hassle should be a basic requirement. Taxonomy was probably the single most hotly debated topic when it came to building our own system. There is no right or wrong answer here, just a consensus that will continually evolve.
Next, there’s the time and effort factor. Creating documentation adds extra time to the project, is generally laborious work, and then rapidly becomes obsolete if not actively maintained. Finding a way to essentially make documentation a natural by-product of our existing workflow with minimal additional effort would be a huge bonus.
And last but not least, there’s the question of audience. So far, we’d operated on the basis that our documentation was for ‘everyone’, which is as it should be... but without spending a little time considering the different needs and use cases of developers, designers, QA, project managers etc, and then defining a hierarchy of these users, we’d nothing much to steer our thinking on layout, architecture, features and content priorities.
Prioritising users
After a little research, I came across a persuasive article by UX designer Nathan Curtis on this subject, who’s pretty clear on who should be prioritised and why:
"Serving everyone doesn’t mean serving each equally. Engineers may visit doc 5, 10, or even more times daily. It may even be an open window adjacent to their code editor! A designer may visit less frequently, comparing this to that and occasionally absorbing details. A content strategist or researcher may visit rarely to support a decision.
"So, who’s most important? My experience suggests a clear starting point: systems are first made of, by, and for engineers and designers. While others welcomely contribute and benefit, they are secondary. Serving secondary audiences less than optimally may be a necessary tradeoff."
"What about engineers versus designers? If I had to choose one, without any context, I’d favor engineers. Getting 50 engineers to code well-designed components is more likely to result in cohesive, efficiently built experiences compared to 50 designers reading tomes of guidance about decisions already built into that code.
"Audience priority depends on many factors. Expect designer and engineer needs to collide, and attempt to optimize for both. If you can’t, orient tradeoffs towards those using the material closest to the final product, usually code. That means engineers first, designers second."
medium.com/eightshapes-llc/documenting-components-9fe59b80c015
Prioritising content
So what does this actually mean in terms of requirements then? Of the four areas of component documentation listed by Nathan Curtis, two are clearly must-haves for engineers:
- Introduction of component’s name and succinct descriptive content that sets the tone of what’s there.
- Examples illustrating a component’s named variation, states, and other dimensions, preferably paired with and rendered by code instead of presented via static images.
- Design Reference including Use Whens, Do’s and Don’ts, and guidelines for visual, interaction, and editorial concerns.
- Code Reference detailing the code’s API (such as Props) and other implementation concerns.
That’s engineering covered, but what about the design reference? In terms of the functionality needed for this, it’s not much of a stretch – text and images mostly. However, the definition above strays into what could be considered quite high-level digital brand guidelines territory, which takes no small amount of work to write and maintain. So being pragmatic about it – unless the client has specifically requested per-component design documentation as a deliverable, it doesn’t really fit in anywhere as a by-product of our existing workflow, and it’s unlikely to happen. Still, the capability to add this information should be a requirement, so we’re able to include it should the need arise.
It makes more sense to focus time spent on design documentation by starting with the essentials: low-level global design decisions first, and building up from there. Design tokens such as colour, typography, spacing etc. will be referenced often, by both designers and engineers, and these variables and the utility classes that come with them need to be fully documented.
Over and above the design tokens and utilities, ideally we’ll include an icon library, and some of the basic elements such as buttons and form inputs. This is an area where what’s included will change from project to project, so flexibility is key.
What’s out there?
There are a wealth of documentation solutions available that are compatible with React. But bearing in mind that one of the key criteria we’re looking for is something that fits in with our existing workflow, all of them sit outside the main project as a separate entity that requires a lot of manual work to populate with content. Most of them produce great looking documentation, some of them have cool integration features with Sketch and Figma, and one or two include the ability to detail component props automatically, but overall they’re not quite what we’re looking for.
Hello Storybook
Storybook is a bit different. Originally built with just one use case in mind – to design and develop UI components in isolation in a sandbox environment that lives inside your project.
"Developing UI components in isolation makes it drastically easier to develop hard-to-reach states and edge cases. Which in turn results in durable components."
blog.hichroma.com/the-delightful-storybook-workflow
It’s a highly useful development tool, and just by employing it, you’re building a component library that comes with usage examples and code reference automagically built in. Jackpot.
"Storybook is all about writing…stories. You can think of a "story" as a single state of one of your components. In keeping with the metaphor here: when you write a set of “stories” for your components, you get a storybook."
seesparkbox.com/foundry/building_pattern_libraries_in_react_with_storybook
This ties in perfectly with the goal of reducing the workload involved in creating and maintaining documentation.
"Stories are easy to write and are always up to date because they use real production components."
medium.com/storybookjs/storybook-docspage
It also ticks the box on flexibility – stories can be organised in any way you want, and grouped into folders or sections.
Adding the low-level documentation for design tokens, utilities, icons etc. is a doddle as a result – I can easily create new sections to house these separately from the main application components, and as a story can consist of anything, I can create some simple documentation components just for this purpose. While there is a little manual work involved in getting all this information in, it doesn’t then tend to change often, if ever.
Addons
Beyond Storybook’s out-of-the-box capabilities, there’s a wide range of Addons available, both official and community-contributed, that can unlock advanced functionality, and open up new use cases for Storybook, such as a QA tool.
The Info addon is a must. It automatically creates a code reference for every component, which includes source code and a prop reference table:
Knobs is another big time-saver. Rather than creating a new story for every permutation of a component, with Knobs you can live-edit props to simulate many states with just one story.
Don’t fancy documenting you design tokens manually? With some tweaks to add annotations to your stylesheets, Storybook Design Token will create a handy reference that sits directly alongside your components – great for quickly referencing token names and values.
Looking forward
Recognising that Storybook has grown well beyond it’s original use case, the folks behind it have recently released a powerful new addon called DocsPage to really supercharge auto-documentation. Unfortunately this was released just a little too late to include in our current project, but you can read all about it here.
"DocsPage is a zero-configuration way to turn your Storybook into a rich, readable document. It’s the first step towards transforming your Storybook into a world-class design system."
medium.com/storybookjs/storybook-docspage
We’re still experimenting with Storybook and discovering its possibilities, but so far we’ve been impressed with the ease of use, and it’s addressed our three core pain points of documentation without breaking a sweat.
Going forward, we’re excited to see just how far DocsPage, together with a steadily growing library of other addons, can streamline the documentation process. There’ll always be a manual process involved somewhere, but the more low level documentation that can be automated by clever systems like Storybook, the more time we’ll have available to write the higher level, richer, more detailed information, and the better our documentation will become.
Why not find out how Kyan can help your team with our Design Systems for modern product design service?
Previously from our Product Design Team:
Learning through listening: some of my favourite design podcasts by Will Poole
Meet the Kyan Design Sprint team by Kyan
Design tools that we're excited about for 2019 by the Design Team
Image optimisation techniques for web by Helen McCarthy
