Documenting the System

Documentation helps preserve the longevity of the Web System.

It is quite common for a team to lead a redesign / rebuild of their site and then two years later that entire team has moved on and works somewhere else, taking their domain expertise with them.

We like to make sure that even a brand-new employee of the company could get up to speed with the entire system and start making changes on their first day of work.

We use three types of documentation:

Figma

Figma is where we document our design system, including all of the modules, components, typography guidelines, etc. There are many ways to do this in Figma, here’s what ours looks like:

Storybook

We store the fully coded modules in Storybook. This includes all the variations that will be available in Contentful. We make sure that the naming conventions used in Figma and Contentful are also used here so that it is easy to move from Storybook to Contentful.

CMS Tutorial Videos

We create a series of simple, short screencasts that show how to do the most important things in Contentful for a given site. The most common videos we make showcase how to create a new page, how to add / edit / delete a module, and how to modify the styles of a particularly complex module.

Taken together, we’ve covered the design system, the usage of the CMS, and the live, fully-coded modules. We’ve found that this is everything a company needs in order to take over the management of the site.

---