Authoring good documentation

Good documentation is vital and shows that you care about your design system and those who will use it. Lacking good documentation practices could spell doom for a design system.

Up until now, we've been very much eyes-on-the-prize, fully committed to ensuring that:

  • Our actual process works like we want it to, from Figma to code

  • Components look good in isolation (in Storybook)

  • Our example application can locally use our components

But we've still not really spent any time documenting our design system, which underpins so much of that.

In this lesson, I'd like to present some ways in which we can meaningfully and painlessly document our design system and still make sure that Figma is our source of truth.

Remember: We do this also because we care about other people, and so that our design system—a complex entity in its own right—can be used at all in a productive manner.

The heart of this matter is that you should try to make it easy for people to do the right thing and what is expected of them.

Documentation is debt#

All code is debt. As it happens, tech debt is not even actually about technology; it's about people and the things we do. As I've already mentioned in a previous lesson, even our design doodles are future debt because they make a certain assumption that additional resources will be spent in the future to actually build these doodles into usable code.

Documentation is debt as much as code is. Writing it means we need to care for it. Therefore, we need to have a clear idea of what documentation is meaningful to invest in. What are your docs trying to answer? If your docs become complicated because of, for example, tech failures, then see if it's more effective to fix the issues and just skip the documentation, which would no longer be needed anyway. Focus on documenting things that have a longer-term validity.

The type of documentation we want to aim for in practice would need to be:

  • Open for us to read and change (a question of policy and access)

  • Easy to write and update (a question of adequate tooling)

  • Ideally, covered by the same work cycle that covers the relevant practical production part

  • Respected in your organization

We can answer the first three in our workflow, using markdown files in our codebase, and in how Figma and Storybook interact with them. Using pull requests means that we have a continuous dialogue about all incoming changes, and since others comment on your work, you can trust that they will complain if something is unclean and undocumented.

Don't share the same format or assumptions for tactical, short-term (volatile) docs as for strategic documents

Use different tools for different needs. The longer-term documentation should perhaps live in another forum and format, such as Confluence or similar platforms. This is, however, beside the point of this course.

Learn from the past; don't repeat it#

The very first reason why we document is simple: learn from the past; don't unwittingly repeat it.

We need to document because anything non-trivial will require context, additional information, and links to other corroborating sources. Lacking those things, we are at risk of creating knowledge divides and siloing knowledge with the "people who were there at the time." Think of it this way: with some sort of historical record, we can learn from what has happened and from those who were before us, even when they are themselves long gone. Without such a record, we may fight the same battles over and over again.

The worst that can happen, and I've seen this upfront, is that you are rearing to promote what you think are new ideas, but you have no clear history to base those assumptions on. Documentation that can be trusted can become a good objective historical record, at least to some extent. There is a reason why dictatorships thrive with public misinformation. While a corporate context is hardly a dictatorship, ignorance is not bliss.

Documentation can be both formal and informal#

Our current (informal) work#

During the course, we have already used a number of informal ways to document our work by creating visible structure and context. Let's look at some of what we've done in Figma:

Start a new discussion. All notification go to the author.