Shortly after we opened up Drizzle, our pattern library framework, Luke Askew started a wonderful discussion of pattern library maintainability in that project’s repository. This inspired me to reflect on the pattern libraries we’d started or contributed to (as well as those that clients established prior to our involvement). Why did some succeed where others failed?
I noticed three qualities that recurred in different combinations. Without at least two, the projects seemed doomed to failure.
When Bootstrap creator Mark Otto spoke about the origins of his seminal framework on Shop Talk Show, he said “I consider our documentation […] the core of the product.” Bootstrap’s docs are so easy to read, use and understand that people don’t seem to mind copying and pasting markup examples into their own applications.
There’s always a risk that the person you’re writing the style guide for will ignore it completely, so make your documentation as user-friendly as possible.
Pattern libraries created by a single team in a vacuum will often unintentionally discourage contributions from other disciplines. Designers might craft a style guide that focuses on presenting interface patterns with static images; developers might adopt an intimidating structure or build process.
…a larger, more worthwhile goal is to create a tool that’s useful for designers, developers, project managers, business owners, and even third parties. A style guide can serve as a watering hole that helps everyone at an organization speak the same language and builds awareness/appreciation of the system.
The only surefire way of requiring adoption and maintenance of a pattern library is to integrate the patterns directly into your application’s infrastructure. Changes made to patterns cascade to the final product, and vice-versa.
At Salesforce we face this very challenge and we came up with an agnostic solution: we define our design in a single location and use a system to cascade it down to all platforms. We call it our Single Source of Truth.
In a perfect world, every pattern library would be User-Friendly, Collaborative and Integrated. But this isn’t always realistic.
Teams may lack the design resources to emphasize user-friendliness. Organizations may be too siloed to support cross-disciplinary collaboration. Your product might have too many distinct architectural endpoints to make integration feasible.
All is not lost! While the “holy grail” combines all three qualities, you can still be successful by picking the right two:
Easy to use and update despite requiring some repetitive work behind the scenes.
Cumbersome to update, but required for any development and a valuable resource for the broader team.
Opaque to non-maintainers, but anyone can become a maintainer. Updates are immediately reflected in the end product.
Ultimately, which qualities you choose to emphasize will have a far greater impact on the pattern library’s success than which of the many fine tools or frameworks you choose to adopt (or ignore). When in doubt, discuss the project with coworkers from every team you hope will embrace the tool.