Step 4: Documenting a design system

When creating a design system it’s important to be mindful that you won’t be the only designer (or developer) who works with it.

Literally documenting the design system was the biggest challenge for me on this project. Normally I create annotated specs — typically these are a series of .psd or .sketch files, to accompany the design(s). A good example of this approach can be seen in my case study for Adobe Portfolio. While specs can contain every detail imaginable, things can still be missed or misunderstood when a new or replacement designer steps into your shoes. We wanted to do better with Plasma!

How do you document a design system?

I started out reading and researching how other teams had done this. Fortunately the Internet is full of answers for this, and many companies have made their documentation public.

Here is a useful list of links to all the online design system documentation of note I found. I hope it helps :)

My initial goal, having seen so many stellar examples online, was to create a website to document the system, specs, showcase example uses, and specify guidelines for all patterns and components. It would act as a quick reference, or a bible to study in detail.

However, I didn’t want to be held back by the design, build and time constraints of creating a website for this. So to get started I simply created a new Google Doc and started typing. As the document grew I realised it did exactly what we needed it to — the only reason to create a public, branded website for this would be as a ‘pride project’ for WeWork Digital, or as a resource if we open-source the system.

But for now, Google Docs proved to be the perfect medium! It’s easily accessible by all our team, plus they can comment inline, which is great for feedback. The ‘Document Outline’ feature of Google Docs, plus the ability to link/anchor to bookmarks and headings within the document, provided ample navigation. Jobs a good’un! …as we say in the North of England :)

Preview of our documentation

As the documentation is in a private Google Doc, I’ve captured some screengrabs below to give a good idea of how it was constructed, laid out, and what it contains. You can click the images to see each full size.