I spearheaded a new style guide for my current employer a while ago, and it’s been an interesting ride. I’ve learned a lot through this process that will hopefully direct you while (re)creating a guide.

Out with the old…

Like most initiatives, our original guide was launched with much pomp, having been constructed by a committee of UI-minded folks in the company. Also, like most new initiatives, it lost steam before it’s value was ever fully realized. People left, priorities changed, and subtle decisions made during the making of the guide left it hobbled. By the time I came on board the existing guide was a rarely-used, hard to find artifact that had little buy-in from the dev team. No one verbalized this, but I could tell the team felt like it was just another document handed down by product management, complicating life.

“But!” you’re crying… “style guides save developers from hair-pulling frustration”. And you’re right. By the time I started eying a redo of the guide, our team was having difficulty forging ahead with front-end decisions that could have been dead simple by referencing a complete and living style guide. This started my push for a new guide. I convinced the team that there were multiple reasons why the existing guide needed a complete overhaul:

  • It had very few existing entries – The existing guide was never fully fleshed out and large swaths of styles and patterns were never documented.
  • The styles in it were outdated – The guide was rarely maintained and didn’t share the same css/html/js as our ecosystem. As as a result, documented styles were not reflective of the real world.
  • It was outta sight, outta mind – The guide lived on a little-used subdomain and required a password-protected login that no one remembered.
  • It suffered from being disconnected from reality – The guide contained many styles and patterns that were never codified or even used in our system. From the best of my understanding, these were ‘wish list’ patterns that never saw the light of day.
  • Our team increasingly debated – As I mentioned earlier, the team was spinning it’s wheels over simple, easy-to-document rules around our styles.

Our existing guide was a meaningful first start at cataloguing our best practices for UI styles, but quickly fell prey to a “who cares” mentality by the dev team. It wasn’t a document focused on helping them help the user. It was instead a wishlist of what our system should look like, which ignored the messy fact that our system did not look anything like the entries in our guide, and would require work no one was willing to prioritize.

In the end I chose to push for a full redo of the style guide in order to combat some of the inherent problems specific to the original guide’s platform – namely so that we could provide living demos of our styles in an easy to access place that didn’t require the dev team to remember a separate url and set of credentials.

…In with the new

My first step in rebooting the style guide involved actively inviting fellow developers to share what was and wasn’t working well with the current style guide. It wasn’t anything elaborate – just a short online survey that asked to rate the strongest and weakest aspect of the guide, as well as person thoughts on how to make the guide better. This was done not only to validate my own opinions about why the old guide wasn’t working, but also as a way to extend an olive branch to a team that I think felt alienated from the front-end UI and styling process.

After tabulating the results, most of my hunches were proven to be true. Some of the most common complaints were that they:

  • disliked how difficult it was to access simple style guide entries
  • found the current entries so wordy they were verging on being unusable
  • thought discoverability of entries was poor due to ill-defined categories for styles
  • couldn’t easily link to style guide entries in our issue tracker

Getting this feedback was of critical importance. I didn’t want to repeat the mistakes of our old style guide, and wanted to hit this new style guide out of the park by addressing these pain points. I recruited a teammate interested in front-end design and we quickly came up with a proposal for this style guide reboot which enumerated these pain points, as well as a plan for tackling them using measurable key results that we could use to see if we were hitting our mark.

Of course, I did some research too to see what the best practices were for creating style guides. The most influential I’ve listed here:

Building the platform

I listened to the siren song of “don’t build it yourself” for the actual style guide platform when first starting out with the reboot. Maybe I was too dismissive, but I really couldn’t find anything out there that would allow us to integrate with our codebase in order to add live demos of our styles to each guide. On the other hand, I feared an endless amount of work building out a platform.

Fortunately, I felt like we were able to strike a good balance when we went ahead building the guide. We leveraged Symfony (our current php framework) and modified it’s MVC approach such that it was lighter weight and only required adding a new twig template to get a new entry up and running. No fussing around with a separate controller or routing… this was all taken care of automatically by the naming and location of each style guide entry. This reduced the barrier of adding and modifying entries for the team, even newbies lacking experience with the Symfony ecosystem.

Some of the best decisions we made were focusing on lowering the barriers wherever we could for those creating and those consuming content as well as reducing the amount of maintenance needed for entries over time. We rolled the guide into our actual product so it had access to the exact same css, javascript, twig, and programming interfaces. We also prioritized a living ‘demonstration’ section at the top of each entry to quickly give the reader an indication of how the style looks right that moment. Gone was having to navigate to a separate page, using a separate set of credentials, and playing around with a separate ecosystem just to get at a simple entry.

In order to address discoverability of entries, we created multiple ways of accessing entries, via search, navigation tree, and a ‘site map’ on the guide’s home page. Perhaps most useful, however, was performing a card sort exercise with the team to determine how they thought about the navigational hierarchy of our styles. We used these results to help guide us in organizing our navigation, cutting out suggestions from the exercise that just didn’t make much sense.

We’ve been starting to see traction with the style guide as we’ve built it out. If you’re in the middle of adding content to your style guide, don’t fret if it’s not widely adopted at first… for a guide to be truly useful, you need to get it to a critical mass of content. The most important, foundational entries should be there before expecting any large payoffs in terms of team adoption. If you’re still feeling like the guide is struggling for visibility, get it out front and center at team demo sessions and meetings. Introduce individual entries as they’re added. This is a great way to generate buzz on the team – even if that buzz is initially a negative pessimism directed towards your unbridled enthusiasm of using a guide to herd the team’s appraoch to UI development.

In summary…

I’ve felt like this style guide is one of my biggest, highest value contributions to my team. We still have a long way to go in rounding out the content, but I’m already seeing the initial foundational work paying off – few and far between are the subjective flame wars about how to use a particular style, more people are referencing the guide when working front-end, and an increasing amount of developers are actively participating in documenting our styles.