Documenting-first approach

Failed campaign

At every company – I felt the urge to take on design systems and often took the initiative to introduce a design system, even if it meant spending nights working on a slide deck to convince my teammates and superiors.

And once I got to present my slides, I nailed it! Everyone loved the idea of a design system.

Unfortunately, once I wanted to get started, the business said: “No, It will slow development down; now is not a good time.” 

Coming across this way too often, I can safely say; there will never be a good time.

Envy is the road to deliverance

I had to develop a better proposal to make a start more amenable. Then, once the barrier was out of the way, the design system started to take off.

Not at the fourth time – whatever lean-start alternative I was throwing at them, it didn’t move the needle. The business still said no. I felt a lot of frustration as a way forward wasn’t obvious.

I envy developers because they seem to be less dependent on others publishing a site. Well, maybe it could look better with the input of a designer, but at least it was published. And that’s what matters most.

I was dependent on development, budget, and a roadmap to deliver a design system. These are all factors I didn’t control. Did I make it too hard for myself? I was.

The answer to a successful start was redefining how to establish a design system. I based the definition on the one thing I could publish, besides my Figma library – and that is documentation.

Start by taking action

I always love to break down barriers – each new barrier was an opportunity to manifest my abysmal willpower to take it down. But my efforts didn’t always equal results.

Motion in my story is about the meetings I conducted and the presentions I gave. I deceived myself into thinking convincing teammates would lead to success – it didn’t.

Action meant publishing. A guideline is a deliverable, with clarity and alignment as an outcome.

Publishing is a way of automation. It doesn’t need you in the room and doesn’t require your time. Communication becomes effortless. Instead of spending energy to get the design system going, the documentation will do it for you and generate energy.

What’s more, getting feedback on your documentation improves the document and increases engagement. So keep an ear out for people's comments about unanswered questions or lack of clarity. The value of the document to your colleagues will reveal itself.

The power of documentation

I discovered the power of the documentation-first approach while developing a startup product. Let me give you an idea of the situation:

The team working on this startup consisted of 20 developers, 3 product managers, internal and external stakeholders, and a couple of designers flying in and out of the project, all working remotely. Budgets were strict and roadmaps short and action-packed. We had to stay lean, cheap, and fast. An investment in anything like a design system didn’t seem obvious.

Not everything in our operation was lean and fast. I noticed how much time we spent discussing the same matters repeatedly. For example, we designed an accordion holding a few frequently asked questions. Again, to save time, developers decided to hard-code the first two questions and make the latter one dynamic. Unfortunately, everyone, including the PM, seemed to be forgetting these details – once the accordion entered the discussion, the conversation started over again. 

The situation worsened when a copywriter joined in rewriting parts of the app. Then, it got to a boiling point when no one remembered why the ‘time-saving’ solution was there in the first place.

Finally, I decided to write a small Confluence page about the accordion as a first guideline – after adding a couple of visual examples to the document, I published it.

I dropped the link to the document wherever I could: in git repositories, JIRA, and emails. Crediting colleagues in the document contributed to the adoption and credibility of the document. The document became the first piece of the single source of truth.

Design system becomes a reality

My Confluence page quickly showed its value. Whenever the accordion conversation turned up, I dropped a link to the document in the chat. The time it saved us became noticeable. Also, especially for the PMs, it made it easier to give clarity with less effort.

When consulting documentation became an integral part of product development, I realized the design system was shaping. 

The team experienced the benefits firsthand – freeing the way to the next step, developing a component according to the design system documentation.

© 2023 Govern, Inc. All Rights reserved