Design system documentation is not easy to do well. How’s that for an obvious opening statement? Look around the Internet, and you’ll find plenty of excellent examples of documentation sites that are done really well. However, borrowing great ideas from them is not a guarantee the one you build will resonate with your users. Writing is difficult in and of itself. Add to that, the complexity of relaying technical information for a diverse audience consisting, of front-end engineers, back-end engineers and designers, and you’ve got yourself a tasty challenge. The tone needs to inform but not talk down to or alienate. Making the wrong assumptions about users do and do not know might be the deciding factor whether they adopt the system or not. This is the challenge we faced with Uniform-UI-Docs, and how I attempted to satisfy those concerns in documenting our CSS library.

A Helpful, Utilitarian Homepage

Users arriving on the Uniform-UI-Docs (uniDocs) homepage were greeted with a useful, informative homepage. One challenge we encountered communicating with a product team of over 200 people was how easy it is for our users to miss the announcement of a new release. Slack messages are ephemeral. Articles on the company intranet site are often a prime candidate for what not to read. I wanted our homepage to make it easier for users to discover key improvements that might have otherwise been missed. The list of recent releases focused not on every release, but notable releases: the addition of a new component, a fix or other important changes. These teases linked to the full release notes on GitHub. I took pride in writing comprehensive release notes, ensuring users had all the information they needed when deciding whether to upgrade or not. The last thing we wanted, as a burgeoning design system was to alienate users by not adequately preparing them for an upgrade. Upgrades can be challenging enough when you know what to expect. I wanted to make sure we were not pulling the rug out from underneath our users. The rest of the homepage outlined other pieces of the Uniform system: our design guidelines, our React component library, as well as the blog associated with the uniDocs site.

The Component Page

The component pages are hard working. Users coming to one of these pages should get all the information they needed about a given component. The functionality expanded as the system itself became more robust. Initially, each component page displayed the component and possible variants of that component, the associated HTML and CSS. Users wanting to grab the HTML were provide a button to copy the code pattern that they could then paste into their own project. Over time we added theming and examples of the corresponding React component, which linked to that component on GitHub. Adding features to these pages was a unique design and development challenge. With each iteration, I strived to improve the legacy code I’d left myself, repeating myself less and making it easier for others to understand and add content if I were to get hit by a bus or just be unavailable.

Interactive Wonderland

The Uniform Design System provides a total of 16 possible background color options across two different environments (dark and light). When we added theming to the design system, I knew I wanted to give users the ability to see the component in the context of those potential shades of gray and black. These controls also trigger the changes for the component, based on whether it’s in a dark or light environment. The result is both really useful and a delightful way to kill a few minutes. I doubt there was ever a time I was working on the site where I didn’t flip the environment switch and click a few levels here and there.

A Dime Worth of Knowledge

Sprinkled throughout uniDocs are highlighted notes. There were two main type of notes on the site: informative and critical. A critical note warned users of changes or issues they should be aware of. The informative notes communicated key information that might help a user better understand why the Uniform team made a given decision, the importance of using semantic HTML, etc. I often referred to the informative notes as a “dime’s worth of knowledge.” Simple, short notes that would impart knowledge. We had a diverse set of users doing front-end development and coming to our site for information and answers. I the site wanted to be as informative as possible without being too intrusive or slowing down a task someone was there to accomplish. The notes were definitely opt-in.

Consuming Tokens, But With a Twist

Initially, our color variable pages were created with a yaml file I maintained and updated. Each color section had custom descriptions that explained how to use the colors, linking off to more comprehensive descriptions, when that was available. However, as we solidified a token system to ensure all colors across all platforms had a single source of truth, we lost the custom descriptions. I felt those descriptions were important in the context of uniDocs. I spent the better half of an afternoon, figuring out how simultaneously loop over to different yaml files, creatining he color list and providing the descriptions. Like I said working on this site made me a better developer and satisfied my ability to be a glutton for punishment.

Put a Blog On It

As I mentioned, Uniform had a user base with a diverse skill set. We had .Net developers touching our front-end code. We had UI designers, dipping their toes into our front-end code. And we had front-end engineers touching our code. For many, CSS and HTML wasn’t a first or even second language. As a way of filling in these holes, I spent a few days of downtime creating and seeding a uniDocs blog with a small set of articles, outlining how to effectively use pieces of uniCSS. I always tried to think of Uniform as a choose your own adventure product. It’s unlikely users would be able to go all in on the system at once. Refactoring an existing micro-service and fully adopt the system might be too costly in terms of time and risk. However, adopting portions of the system as they make minor improvements is doable. To that end, the blog articles outlined strategies for utilizing pieces of the system without refactoring wholesale. In addition to the blog, we occasionally held talks about writing CSS, using our React components and the philosophies of the Uniform Design System, overall. I took the opportunity of developing blog to make the rest of the site responsive.

Goodnight, Sweet UniDocs 💀

I’m proud of the work I did on uniDocs. However, it was a symptom of an overall documentation problem we had with our system. Our CSS and HTML was documented here. The design philosophies were documented on another site. React component APIs were documented on GitHub. Users had trouble finding the information they sought. We knew this was an issue for quite some time, but stopping progress on component development and creating one, universal documentation site wasn’t in the cards, until late 2017. We combined all our documentation into a new lovely site early this Spring.