Improving Content and Process for Design System Documentation

CLIENT

U.S Bank

INDUSTRY

Banking

SERVICES

Content Strategy
Editing
Writing
Technology Implementation

Description: In preparation for the impending release of the Shield 2.0 Design System, U.S. Bank contracted me to help audit, edit, and migrate legacy content into the new CMS (Zeroheight).

Since I like to leave contracts better than I found them, I also created some additional projects to raise the quality of the documentation and assist with the Zeroheight implementation.

My Process

Original Project: Edit & Migrate Content

The original project was to proofread and migrate legacy content for the REACT platform in preparation for Shield 2.0 Design System release: 

  • Move legacy content over to Zeroheight, the new platform for design system documentation. 
  • Adjust the content to fit into the new template for Zeroheight.
  • Copy edit content to improve clarity and remove errors. 
  • Ensure content adhered to the U.S. Bank Brand Guide.

REACT Documentation Writing Guidelines

As I was reviewing the documentation, I noticed inconsistencies:

  • Sections were not consistent/present on all components pages.
  • There were language structure differences that made the “voice” of writing between components sound different. 
  • There was a difference in language describing components.
  • Some things that were being called “components” actually weren’t (requiring either new taxonomy or adjusting documentation template to properly explain it). 
  • Component pages had been written by multiple authors, and it showed. 

So I made a new goal for myself: Make content structure and language consistent between all component REACT documentation pages. 

While I could do this process for the existing component documentation pages, I wanted content strategists writing new documentation to be able to make new content consistent. In addition to the U.S. Bank Brand Guide, there was a Shield Writing Guidelines doc, but that was written for in-product content, and content on U.S. Bank web pages. There was no specific documentation style guide that would have addressed some of the issues above, or spelled out things like:

  • How long the component description should be
  • How to structure/write the “do’s and don’ts” 
  • Which table format to use

So i wrote one!

REACT Documentation Writing Guidelines

Documentation Consistency Across Platforms

My area of focus was design system documentation for the REACT platform, but we were also soon going to be having Native/iOS and AEM component documentation coming on board.

I started looking at the documentation for Native/iOS (AEM hadn’t been migrated yet). While there would be some obvious differences in content because REACT and Native/iOS are different, there were also areas that all platforms had in common. I started discussions with other platform team members to find alignment on those areas going forward. 

Documentation Content Review Process Improvement

There was a team of content strategists writing component documentation. The “official” peer review process was someone writing in the Teams Content channel, “Hey can someone review this?” There was no time spent for reviews, no one was assigned and accountable, and there was no formal structure or criteria for reviews, which meant that some people (me) were reviewing more thoroughly (I review documentation for accuracy, completeness, clarity, consistency and a copy edit for errors), and some were just doing a copy edit. 

We needed a more structured review process, and needed to define review criteria to get a common baseline for documentation quality. 

I wrote up and presented this presentation to the CS and leadership to outline the issues and my recommendations (and things that i already started changing). 

Getting this discussion started illuminated some upstream issues that had been affecting documentation, namely that some review layers (accuracy and completeness) were being done by content strategists, and should be done earlier in the process by developers and designers (together with CS). 

I also highlighted the need to account for content review time in sprint planning. 

Documentation Content Review Process Improvements

Zeroheight Implementation

My original project was to prepare content to be moved to the new faux CMS, Zeroheight. I keep saying “faux” because it really isn’t a true CMS where content is broken into fields in a database. It’s really just a bunch of pages that allow text and embeds of code and images (which aren’t even stored in a media library for repeated use).

Zeroheight as a product was pretty immature at the time of my contract. As I kept working with it, I noticed a bunch of issues that I knew would be soon be affecting the content strategists working with it after the Shield 2.0 release. So I:

  • Started capturing issues and notified the Content Strategy team about them
  • Forged a relationship with the Zeroheight account person to get both bugs and feature requests into their pipeline
  • Became a de facto Zeroheight QA tester for illuminating potential problems and testing the fixes Zeroheight sent us.

Charlene is a top notch writer and editor. What surprised me was her ability to investigate, find problems, and bring ideas to the table.

She has a natural ability to see the big picture and find unexpected ways to bring everything up a level. From process improvements to writing consistency to format and structure, she’s able to see everything as it could be and refine deeper content strategy and content governance.

Beau Ulrey

Senior Design System Manager

U.S. Bank

Let’s Work Together

Tell me more about your project

Is there a content problem I can solve?