Frontend Architecture for Design Systems

Chapter 17. Red Hat Documentation

As I’ve looked back on the year-long process of developing the new design system for the Red Hat website, I realized that the entire project started with a need for documentation, and grew from there. The original request from management was to develop a style guide of our website’s most commonly used bands, and make them available for other Red Hat web properties to use. It all started with a handful of Sass partials and a Hologram style guide, but it grew into so much more.

Stage 1: A Static Style Guide

As I wrote in Chapter 15, Hologram is a documentation tool that looks for specially marked comment blocks in your code, and converts the contents of those blocks into a style guide. Having heard about Hologram from Nicole Sullivan, I felt that it would be the perfect tool for us to document the layouts and components we were building.

Working inside of Hologram was quick and smooth. Each component or layout had its own Sass partial, so we placed our documentation block at the top of each file. The documentation included everything from our intentions for the component, to its capabilities and limitations, to a sample of the HTML markup. The markup allowed us to get a quick preview of the component without having to fire up the CMS, which made prototyping, cross-browser testing, and visual regression testing a lot easier.

Along with our library of components and layouts, we spent a great deal of time developing onboarding documentation, which ...