UX style guide techniques

Question

I've recently started a major redesign for a large web-based financial tool. To aid future development, I'm planning on generating a UX style guide that outlines best practices for things like forms, page layouts, animations, etc...

The existing application is a big jumble of forms with little grouping or organization. I can see a few major categories, (Object CRUD forms, static data, user session management controls, etc...) but there's a lot of very custom functionality that doesn't fit the mold.

The company I'm working with does it's development overseas, and this documentation is intended to support future development. I'm not looking to design the most amazing UX ever, I just want things to be functional. What's the best way to communicate designs to remote teams?

Here's my question:

What's the best way to approach a big messy project like this? (Major groups first, then focus on each custom function? Do you even include the custom functions in the documentation?)

Answer 1

Example Style Guides

For example style guides applicable to applications, you can leaf through with the usual platform style guides (e.g., Windows, Apple, Gnome) for the organization, issues, and topics you may want to have. Many topics in these guides are not relevant to form-oriented UIs, but most of the guidelines for controls, messages, and dialog boxes have compliments for forms. There’s also guidelines for web sites, (e.g., usability.gov), but these will generally be less useful for applications.

What to Include

For the basic approach, see answers to How did you create design guidelines for your organization? To answer your specific question, I make a distinction between “elements,” or pieces of a UI (records, fields, layout, forms, command, and feedback), and “functions” (what some might call “patterns”), which assemble multiple elements into a standard UI for a common step in the user’s tasks (e.g., login, query, reports, undo, sort, zoom, help). I cover both in a style guide.

The idea of a style guide is to avoid you having to design everything yourself, so if a custom function only exists in one form, don’t include it in the style guide. However, you may want to include components or abstractions of the function that are commonly used throughout the tool or suite.

The Deliverables

Ideally, the ultimate form of the style guide should be what works best for your users –not the tool/suite users, but the developers and designers that will use the styled guide to make the tool. A style guide should make their job easier, not harder. If it’s too hard for your users to find the right guidelines for a particular case, or learn and understand them, or implement them, they’re not going to. You can apply your UX skills to making the guideline deliverables by interviewing and observing your designers and developers to find out what will work for them (in your case, you may be limited to phone interviews with your developers; better than nothing).

This implies the product may employ multiple media. Chances are the “main” product will be some sort of hyperlinked document, which has obvious advantages for reference material. However, there may also be a summary quick reference guide or checklists, printable posters to promote the guidelines and highlight key features, a library of style-guide-compatible templates / patterns / CSSs, and seminars and workshops (possibly conducted remotely) for you to personally introduce the guidelines and show their advantages for the designers and developers. Frankly, creating the guidelines is only the start. Most of the work is promoting and enforcing the guidelines. Try to get the time, budget, and organizational support for that.

Answer 2

I know there's an accepted answer, and I usually do quite agree with Michael, but still this does bug my mind for two days.

As a developer, I hated the Apple HIG

It just didn't tell me what to do, how to do things in practice.

The Windows Guideline was felt as "empty", but it could be that it did because it seemed, on Windows, actually noone follows them.

Bear in mind, that I actually had to have a really intimate relationship with the Windows GUI: we were required to be able to write short Windows programs even on paper.

I knew every single widget, how it works, what's its purpose, and how can it be called. By heart, literally.

It was like a forced marriage.

Still, I didn't know how to create stunning stuff, and neither the HIG told me how to do that.

If it's not the HIG, what made OS X applications so uniformly good?

Of course, the Apple products themselves were designed marvelously, and everyone just tried to copy them. When one copy succeeded well, they copied the good parts from there as well. But devs understood the patterns because they used the apps themselves. Whenever a Windows user developer was required to do mac apps, the result was close to a complete disaster.

(If the devs aren't using the system - like, you mentioned elsewhere it's a banking software - prepare for some bad stuff)

Perhaps the good metaphors helped as well: well-designed widgets were connected to each other just like lego bricks.

But also: they had templates: you could say: it's a document based web app. It's a core data web app. I'm pretty sure the web is full of CoreData + WebView tutorials somewhere as in 2006-2007, we've just seen literally a plethora of such apps.

Design Patterns in their original 70s sense are recipes: "If you have this problem, do this": once you establish how to approach the problem, you are on a winning path.

A visual language is still a language

And the widgets are its vocabulary.

For me, bootstrap looks like this:

The developer is asked to write a complete letter written in this language.

Worse: the developer isn't interested in this language.

He isn't learning this for fun, he's told to use it. Some rationalization would help, but in case of a webpage's language, outsourcing, with a separate domain, no user contact, devs just won't care.

So usually what happens here is that the dev opens the vocabulary, patches things together, and submits code.

You need a complete phrasebook instead of a simple vocabulary.

Again, here, letters are to be written. In Chinese.

You need to tell, when a phrase is to be used. You need to show examples, most probably from existing applications written in the same language for the same problem domain.

Every visual language has an underlying pattern language, even if it's implicit

Alexander's classic is a good read. He was the one who introduced patterns into Engineering thinking, and through Software Engineering, it landed in UX as well. A bit off topic, but it's worth to read his IEEE talk.

What you try to achieve with a UX style guide is very-very similiar to what Alexander tried to achieve with his pattern languages: he tried to define the generics, and put the decisions into users' hands.

(Note: into the users' hands, not into the developers' hands)

But I still think recipes are important: a design pattern catalog is still a catalog of phrases. It might be that it's more like the Oxford Dictionary (containing definitions, when-to-uses and examples) rather than a simple vocabulary.

That was completely missing from the HIGs. You stood there, there were general guidelines, and you were like, "OK, so, how do I start?"

An OS HIG is not your guide, exactly because an OS HIG is written to the general case: from drawing apps to mp3 players, from mail readers to hospital catalog systems, everything could be run on an OS in theory.

The same goes for Twitter Bootstrap: it's a generic design language.

You need to find your specifics: where can you tailor the content?

Edit:

What I am talking about when saying specifics?

First,you'll surely identify the patterns of the applications.

There'll be generally two kind of patterns:

• Architectural patterns, that is, what kind of applications are there mostly (you mentioned most of them are CRUD)
• Widget patterns, that is, you'll actually find some specific UX design patterns which can be defined either as widgets or interplay of widgets, and you'll define an according widget library to them.

You also have to specify a third category, usually strongly connected to the first:

• Layouts

Designing Web Interfaces did an excellent job on collecting what are the typical layouts for web applications. I'd recommend the book anyway.

You need to distill this to your own cases. Especially, you'll have to find application modules which would actually benefit from these layouts, and design them fully.

Then, make developers a choice: What kind of application are you building? A Dashboard? A form system? This is the layout of a form system, these are the required elements, these are the optional elements (+when to use), this is how they should work together.

It'd be a good idea to teach devs to actually think in user flows, but I doubt it'd be an easy case to devise a full UX-oriented process, esp. if you're outsourcing.

The devs will use these if it's less effort to use it and make up something on their own than to mess it completely. That is, if you have full boilerplate codes to use, which they can just grab, it'll work fine.

Also, provide them with a set of rule of thumbs: instead of telling that "accessibility is important for people with visual impairments and contrast and color blindness and blahblah", it's much easier to follow that: "all pages must be white on black, no red paired with blue is allowed".

Sure, less fantasy, but I mean, are we building good-enough solutions, or try to make full-blown UX designers out of devs?

The downside will be that devs will echo these rules-of-thumb even after years, and they won't hear about it debunked. Examples are the 7+-1 rules (they still teach it at University!), and basically antyhing which you'll find at UX Myths No, they won't read the descriptions and constraints.

But I guess these would be someone else's problem...

Answer 3

Overseas development is often code for 'poor' development. I've found no amount of style guides will resolve those issues. But that's a different topic.

As for what works, it varies wildly from team to team, project to project. As we build more complex web applications, with more complex interactions and the like, I'm finding the better path to go down is pattern/component libraries.

These are living documents and are designed as a central repository for UX, Dev and the Business. The idea is to create a central hub that everyone can pull from.

You'd identify a component that needs documenting. You mention Forms in your example, which may then have a large number of individual components. Let's take an Option Select, for instance. Your document may then contain information including:

• Name of pattern
• uses (when to use it, when not to use it)
• Visual styles (colors, fonts, sizes)
• Interaction documentation (describes the behaviors of the component)
• alternate versions
• sample HTML/CSS/JS (for dev team)
• sample wireframe patterns (for UX team)
• error states
• accessibility requirements

The drawback? I have yet to find a product that can manage a pattern library well. I've seen it tried with SharePoint, with Axure, with Word, but all have drawbacks. The best option in terms of online tools I've seen is patternry.com which seems to have potential, but is also lacking in areas.

Barring all of that, and combining the fact that you are outsourcing development, if your team and organization can support it, really the best deliverable is the presentation layer code. No amount of paper documentation will result in a perfect translation once back from development overseas so the more you can do yourself, the more control you will end up having over the UX in the long run.

Answer 4

I suggest you use a framework. I use Twitter Bootstrap. It has its own style guide and guarantees a level uniformity with little effort.

Answer 5

I recently came across the one below and asked them permission to use it as an example to one I am writing myself. Permission granted:)

http://www.labor.ny.gov/ux