How Do You Write for Your Team?

There is no one-document-fits-all. What document is right for documenting design? "It depends."

When we are doing conceptual design, we make pretty pictures. Consider our conceptual alarm clock widget (pdf). This document is a combination of words, use case, wireframe, flow charts, and more. There's something for everyone! This document represents a consensus of what is to be designed.

Note, however, that many people won't read the words. Lots of people can't understand a flow chart, or visualize a final design from a wireframe. And yes, all of these people are associated with product development.

When working with interactive gestures, documentation can get even more interesting. We'll use visual communication as much as possible; we can use animations where necessary. Of course when we use an existing set of gestures, such as when designing for the iPhone's gesture set, then you can use a symbol to represent the existing gesture ... Kicker Studio has provided a stencil for these.

With the above limitations, it is clear that no document can be instantly understood by all, but we continue to improve our Concept of Design document to get as close as we can. And not by adding pages, but by actually revising the manner in which we depict the design. The eleven page (with title and marketing blurb) widget document is as long as they come, even for multi-platform deeply complex systems; it's an executive summary.

Detailed design specifications have some of the same issues; traditionally only some people read them in any detail. But if developers don't read them, your design doesn't get executed. We try to talk in appropriately technical language, use annotation and numbering schemes that support traceability, include change logs, and so on.

And, unlike the concept documents, we often try to make these long, basically for the sake of being long. IT documentation is very wordy and repetitive. If your design is very cleverly object oriented and can be adequately communicated in seven pages, no one on the development team will believe it. 30, 50, or better yet 80 pages, now those are specifications documents.

When we do an expert review, we aren't really talking to Marketing. The purpose of this document (download .xls sample) is instead to offer specific, concrete actions for the Product team to approve and the Development team to implement. The persuasiveness is in the precision. So we tell them where the issue is, what the issue is, why it is an issue, and how to fix it. It's immediately actionable.

I first started doing the expert reviews back in my Sprint days, when I was tasked with helping external companies with their mobile web site or mobile application UI. We couldn't invest a full design cycle; I might need to work with five different partners over a two week period. So first I wrote a style guide, a document that contained requirements and recommendations for this type of design. The more I reviewed, the more human factors principles I applied. The more I reviewed, the more design principles I applied. And partners would get a list of changes, much like our current expert reviews, that they could work with.

And you know something? Even though I worked at an operator and was creating work, I didn't get a lot of pushback. After all, I was helping them improve their product.

So what does a deliverable look like? It depends.

Get your own site or app reviewed.

Hello Barbara,

Great post, thanks! I Twittered this back when you first published it, but I’m now having trouble downloading the Alarm Clock Widget example document. Your server is asking me for a username/password.

Are y’all not sharing that document anymore, or am I just doing something wrong?

Thanks for your time.

Kind regards,
Brian

Oops. That’s my fault. We’re cleaning up the website (vs. blog) part of things and got overzealous. Having someone put it all back now. I hope.

If anyone still has issues downloading anything do comment somewhere and we’ll notice and try to fix it.

Steven,

Thanks for your help; I appreciate it. Have a great day and keep up the inspiring work!

Regards,
Brian