Many of us work in places where design guidelines for components, patterns, and heuristics are already developed for the products we’re working on.
Many of us do not.
I went from super-documented world to please-write-documentation world and TBQH I am in my glory because I get to write rules and rule sets and examples and OMFG I love my job right now. I Am Information Architect Hear Me Roar. (I don’t even make most of the rules, I just write them down, and it’s still oh my god so cool.)
But you might not be so thrilled at the idea.
If you’re in a place where the component documentation doesn’t exist (assuming that you’ve reached the point where you’re creating shared components instead of having every developer hand-code her own accordion), at some point you’ll want it, especially if your design and development team is growing.
Consider it moving some of your brain storage into archive, so that other people can get to it if they need to and they’re not calling you on your vacation to question the margins on a button.
In other words, it’s worth the effort.
But if you’ve never done it before, you may not know where to start.
Where to put the documentation
In this, the age of the Agile team, even finding a place to store documentation can be a challenge, because projects don’t generally store requirements and specifications and assets with quite the… zeal… that we did in the pre-Manifesto years.
Choose a place that you’re going to be able to store the documentation long-term, because moving the documentation is a great invitation for other people to stop reading the documentation (assuming they ever do in the first place).
Also choose a place that isn’t associated with a specific project. You don’t want to have to remember which of your 11 projects in 2012 involved the button redesign. You want to remember that this is the new button standard, and therefore it is with all the other standards, regardless of the project that kicked it off.
Good places to store your component guidelines include wikis, SharePoint sites, an organized location on a Google Drive, or something similar. Ideally it’s somewhere that your teams go on a regular basis because they’re putting other stuff nearby, and it has a search engine built into it.
Bad places to store the guidelines include your hard drive (share, dammit!), PowerPoint presentations (it will grow to the size of Kentucky), a random shared drive fifteen folders deep in a folder named “Beware of the Leopard”, or anywhere that’s not searchable.
Even though we don’t expect people to read docs every day, we want them to be able to find them, and predict where new ones might magically appear.
What file format to use
We build web assets and work on the web and test on the web, so one would think the natural answer to this would be “on the web” and one would believe this to be complete and correct until one is handed a three inch binder filled with printed specs.
Yes, this has happened to me this decade. Twice.
Seriously, use a web format. Put it on a wiki or a SharePoint doc or a Google doc. Put it somewhere that people can subscribe to alerts when you make updates if they want. Put it somewhere that you don’t have to repaginate a whole document every time you make a change. Your sanity will thank you.
And cross-link the everloving hell out of it. It’s almost impossible to talk about the reasons to use Thing A without mentioning at least Thing B — you’re working in a design system here, after all — so make sure that Thing A’s spec links to Thing B and vice versa. Build a hierarchy. If your Information Architecture skills aren’t where you’d like them to be, go find one and bug them until they give you some tips or guidelines.
What a spec should contain
Here’s where the YMMV really kicks in.
The spec should look like what drives the design decisions, not what drives the implementation decisions. The goal is to provide the “why” and “when” behind the “what”. If your UX team hit the lottery next week and left, and the development team had to start making their own design decisions, could they use your guidelines as a good heuristic until the company hired a new design team?
The spec should look like whatever your team needs. If you see sections below that don’t fit your needs, skip ’em. If you think of things you need that aren’t here, add ’em (and hey, let me know).
Page title: The component or pattern you’re describing.
What it is: This is where you explain what the heck they’re looking at. It’s your chance to say “Buttons do things and links go places” or “Accordions are a content container” or “Menus are for navigation” — things that are obvious to you because you do UX design but if you brought on a really green apprentice you’d actually have to say out loud.
(This is a good time to point out that linking to Wikipedia can save you a lot of typing.)
What it does: This is where you explain why someone would use it. If you can’t explain why someone would use it, perhaps don’t build it?
When to use it: What are the benefits of using this component over its nearest neighbor? For example, the Accordion spec should explain when to use an Accordion instead of a Tabset. (A Tabset should do the opposite).
When not to use it: When is this inappropriate to use? This section is going to include the places where the component’s nearest neighbor. For example, you’re on the Accordion page, but you need to tell them why the Tabset might be the better choice.
Note that “When not to use it” is going to be much longer than “When to use it” because people love to show you how they can abuse your component. You can count on your team to give you plenty of counter-examples over the years. “Don’t use a button where you should be using a toggle or radio button” is a personal favorite of mine.
You can also add counter-examples from the web to this section. For example, if you’re providing charts, add some of the The 27 Worst Charts Of All Time.
How it’s structured: If there’s hierarchy in the component, or other Information Architecture elements, explain them here.
What it looks like: This is a space for the visual design spec. (The visual design spec describes the size of the component’s elements, colors, font size and color, and all other visual design details. That’s a bigger topic than this article.)
Someone on your team is probably creating the visual design spec using Photoshop or Illustrator or Omnigraffle or whatever, so this is really just a place to put a picture of that spec so that everyone else can see it. If you use an image that is smaller than “actual size”, make sure that people can click into it to see the details. (Always assume your reader is a 40+ year old grouchy woman with bad eyes and a sharp stick and we will get along beautifully.)
How it behaves: Describe the interaction design, and if possible, link out to demos. Even if the demos don’t use the production code, demonstrating the expected behavior is a lot easier to develop and test against than a written description of the same.
Approved exceptions: You’re going to have them. There’s always some weird case that doesn’t align with all the others. For God’s sake write them down.
Write them down so you don’t look at something 18 months later and say “who the hell approved this?” and find out it’s you.
Write them down so you remember that this component was coded the hard way for a really good reason — three years later you’re going to want to simplify this component and totally forget about Weird Case Here and discover after hours of work that you can’t simplify it.
Write them down so that when you update your design in five years, you don’t have to go hunting for Weird Case Here, because your doc already makes a note of it. (And hey! Maybe now it’s not a weird case anymore and you can throw it out!)
Usability Research Results: In most cases you or your Usability Researcher store your results based on the project or the interface, and not necessarily organized by component. If you know Study X covered this component, and that users commented on the component in a way that changed the design (or validated it), link to that report. This not only enforces the message that your designs are data-driven, it makes it easier to find the results later.
Additional resources: People are writing about all of these things all the time. If you find articles about the topic or component you’re writing about, link to them from your spec.
There are two reasons to include additional resources. First, if you do have to argue for the validity of a design component, this is a quick and easy place to remember what someone in the industry already said, so you don’t have to spend half a day searching. Second, you want people to know that the decisions your team made in designing and developing this component were not pulled out of anyone’s ass. You used industry knowledge. You used data. Show your work, and you’ll be more respected for it.
My work in-box has a special folder for articles I read at home that need to be moved into the work wiki as references. It’s my favorite Friday afternoon chore.
Don’t expect people to read it
Seriously, don’t. Your component documentation is not the New York Time’s Fiction Bestsellers list and nobody reads it for fun. Your team has better things to do. Besides, they can ask you if they have a question.
Your component documentation is for you. You and your team make a ton of decisions about components and how they should work. You record it in a spec so you don’t have to store it in your brain anymore. This not only ensures that you get to use that part of your brain for something more immediate, it also ensures that your faulty memory doesn’t change the story later. Write the specs for you and your UX teammates so you can remember the what, the why, and especially the exceptions, that drove your less-predictable decisions.
You still want people to be able to find the specifications, and occasionally you’ll have non-UX team members who actually do read the specs (especially if they’re building the components). You want people to know there are rules behind the design, they’re good rules, and if those people look in a semi-obvious place and use the search engine, they’ll find the rules.
The specs prove that your team is not full of capricious designers randomly picking colors or behaviors, that your work is researched both in-house through usability and through external validation in other UX designers’ writings. You want to build trust in your authority.
But you don’t want to expect people to read the specs constantly. Hopefully, they gather dust, because dust means your component is working and the specs don’t need to be updated, and nobody’s questioning the design. And if you occasionally have to email a link to a spec to a C-level executive to prove that — no really — you thought through the buttons, well, at least you don’t have to write it in that moment!
In conclusion…
Documenting your specifications will help ensure you remember what decisions you made and why. The details that you provide are there to both validate your decisions and remind you why you and your team made them. Especially if you’re starting at a position of no documentation, even the simplest of shareable findable explanations of your decisions will pay dividends down the road.
They make you a stronger designer because you’ll be practiced at justifying your decisions in words, which in turn makes you more prepared to handle any issues that come up. They inform and educate. They cross-reference to research and analysis.
Best of all, they’re exactly what you make them to be, no more, no less.
