Documenting your Design System: The Convince Your Boss Edition

For most engineers and designers, there’s a tiered system of priorities when it comes to what you’re going to work on. On top, the focus is on building the product. This makes sense. If you don’t ship the product, and then improve it, you won’t succeed as a company. Check.

Second down comes the tools and product-focussed processes that enable the top tier. These are the tools you actually use to produce the product (VS Code, Figma, Github etc.), and processes that tell you which direction to point in (roadmapping, planning etc.). These require less focus and attention in setting up and maintaining than designing the UI or coding how it works, but are nonetheless crucial to actually delivering on that top level.

Third down the stack comes your team processes and documentation. The good thing with these are that they don’t usually take a load of resource to maintain day-to-day. However, they do take a while to set up. Also, build them in an inefficient or non-scalable way, and they can really take their toll on the tiers above them.

The three tiers of importance when it comes to building products

One of the problems with design systems, is that they often start out in an organic, slapdash way. The design team have probably started to componentize their work in the design tool, and the engineering team have done the same in code. Heck, they may have even set up a Storybook instance, and the designers might’ve started calling their colors the same thing as the engineers. It all feels like it’s coming together, but now you want to formalize it…

From all the folks I’ve talked to (and having been there myself), the usual argument against documenting is resource. Both the designers and the engineers know that documenting will likely speed up your process, but it’s not an easy thing to quantify. Also, documenting the design system always seems to fall on the mythical ‘design systems’ person that you’re consistently six months away from hiring (nb: if you haven’t proved the worth of the system or the documentation, this person won’t get hired).

So how do you convince the powers that be (and perhaps even your own team) that you may need to focus some very valuable time and resource on your design system documentation?

Top line reason: Less time on process = More time designing

As a top line – The more of your systems and processes that are documented, the less time a designer will have to spend explaining, educating around or reinforcing them. The less time a designer has to spend on the explaining and educating, the more time they can spend focussing on the problems they are trying to solve, ie. shipping stuff.

In a previous role, we had a real problem justifying the resource required to document what we’d started of our design system and processes. We had 5 product designers across multiple squads, with each designer servicing a sizeable engineering organization. On the other hand, our engineering org were pretty solid when it came to DevOps and documentation. It didn’t surprise me that after surveying both, I discovered that 10% of an engineer’s time was spent on ‘process tasks’, whereas with designers, it approached 40-50% of their time.

What were these process tasks? Team-wide PRD breakdowns to establish what patterns we should use to tackle the problem, explaining and critiquing UI implementations, back and forth with marketing on whether the brand was coming through, back and forth with copy and localization on copy processes and copywriting, and onboarding team members to projects. How much of this could’ve been solved with better documentation? Probably a lot.

So first step: Talk to your design team and get them to analyze their working day. How much time do they spend on process? How much of that time could be spent working on shipping the product faster? Business owners always love the words “I can make us ship faster”.

But let’s break this down further…

Reason one: Avoid falling into the ‘Crisis of Quality’

I feel like any business with a maturing design practice ends up with the same crises. One of the common ones is the Crisis of Quality. You’ve adopted Spotify’s squad model, you’ve empowered your product managers, designers and engineers to meet their OKRs, and everything goes pretty well… for a while. All of a sudden you start noticing diverging patterns. Some parts of the product look way more polished than others, and two teams have just solved the same problem with different solutions.

While there are some bigger product process problems you potentially need to fix in this scenario, setting up and documenting your design system is a key way to manage and mitigate the design side of this crisis. If you have your styles, components and patterns documented, and your principles and examples of quality clearly defined and accessible, there’s less chance of your teams diverging.

Getting parity between what exists in the design tools and what exists in the codebase can be a challenging process

Reason two: Get the designed product to look like the engineered product

Designers are, usually, pretty good at designing nice interfaces. There are decisions that go into things like spacing, placement, sizing, hierarchy etc that make the interface easy and delightful for a user to use. They have trained and worked to gain this knowledge and build this skill. Most engineers haven’t done this. Which is completely fine, because they weren’t training to be designers.

Similarly, there are a bunch of constraints when implementing UI, whether they be platform constraints, good practice or cost of implementation, that an engineer knows inside and out, that means that the design they’re handed may need to change when it’s being implemented.

Because of this, each time a design is handed over, you need to commit time to explain the implementation in a lot of detail to see what can be traded off and what can’t. Another way to tackle this is to have documented components, where this discussion has happened once, been documented and can be referenced. As a bonus, documentation often lets code implementation and design be viewed side by side, so you can see where there are differences.

Reason three: Have conversations once, document it, then send a link to onboard anyone else

This one has been skirted around in previous reasons, but one of the biggest time sinks when it comes to growing teams is how often you have to onboard people. Not just onboarding new joiners, but onboarding existing colleagues to concepts, patterns, principles or anything that they haven’t had to work with before. You probably won’t ever get to the point where you won’t get asked any questions, but sending a link to your documentation can cut the time down so the conversations you do have to have are as productive as possible.

Reason four: Get that tight brand to product sync everyone dreams of

In a previous role, I worked with two different design teams – the product team, and the marketing team. This set up is far too common, with each team reporting into different leads. What I found after doing this for a few years is that no matter how many syncs, critiques or Slack channels you create, it always ends up feeling like two teams, because each team isn’t involved in the day-to-day of the other team.

It’s not a silver bullet, but having both teams as an equal member in the documentation of your design system, means that it’s really easy for brand to feedback to product, and product to feedback to brand, with each having full access to the reasoning and implementation of particular features. Also, similar to the engineering-design consistency note mentioned above, having brand and product documented alongside each other, makes it really easy to spot any inconsistencies between the brand and product and call them out.

Design system documentation tools make documenting your components, principals and processes easy and accessible

Reason five: You don’t have to ask permission (maybe just a little forgiveness)

Documenting feels like a big task and a big investment, and yes, if you want it done correctly it should be properly resourced. However, you can make a start relatively easily. First off, platforms like zeroheight work on a freemium model, so you can jump in there and start with your documentation without any funds needed. Next up is choosing what to document. The base styles are always a good place to start. What are your colors, typography, spacing and grid systems? What are your design principles, and how do you write your product copy? However, these are also the things you probably have documented somewhere already.

My suggestion would be to talk to the design and engineering team. What component or pattern do you use that causes the most debate? What pattern do you feel like you’ve needed to explain over and over again?

Once you have the bare bones of your documentation, likely pulled together in a few hours, this is a perfect supporting document to go to senior leadership with to show them the value of what it is you can create. You should also have a good idea of how easy or hard it will be to do the initial pass at documentation, and how much time it will take.

Where do we go from here [cue Buffy musical episode]?

We’re going to cover off in a future article how much resource you should assign for a successful design system, but the short answer is: it should grow as your system (and team) grow. At first, it is very achievable to have documentation the responsibility of the whole team. If you’re using a documentation CMS (like zeroheight), this doesn’t just have to be the design or engineering teams either. And remember, the more people involved, the less time you’ll need for explaining things to folks. From there you can continue building, measuring and improving, because just like any product that shows value, a design system is not meant to be finished, shelved and left to rot.