Re: Design specs (Was: Design Methodology for GUI

28 Jul 2004 - 3:14pm
10 years ago
8 replies
687 reads
mojofat
2004

There seem to be a lot of different ways to approach spec writing, but for anyone that's interested here is one way to go:
http://mojofat.com/tutorial/

I mostly agree with all of Jim's observations about what a good spec has, although my experience is that trying to defend every decision in a spec is not the best way to go. I prefer to write the spec as I want to see the product designed (functionally and visually) and then defend any decisions on a case-by-case basis in review sessions.

-al

---------- Original Message -------------
Subject: [ID Discuss] Re: Design specs (Was: Design Methodology for GUI
development)
Date: Wed, 28 Jul 2004 10:04:42 -0700
From: Jim Drew <jdrew at adobe.com>
To: discuss at interactiondesigners.com

Elizabeth Bacon <eb at elizabethbacon.com> writes:

>What is QE, exactly?

Well, there's a big old Pandora's Box for you. <grin>

"QE" stands for "Quality Engineering". It used to be know largely as
"Quality Assurance", and the Microsoft-approved term seems to be
"Test Engineer". (Which to me minimizes/denigrates the discipline,
but if you want to job search for the role, you use what the
800-pound gorilla uses or you lose 50-90% of the hits.)

(I'm sure there could be the same sort of "what to call it" arguments
as with Interaction Architect/User Experience Designer/whatchagummi.)

QE usually breaks down into "black box" and "white box" testing,
which are roughly manual, through-the-UI testing, and automated or
API testing.

In my case, I've specialized over the years in "User Interface
Testing" (whatever that might mean; as expected, it's bound to be
broader than any easy definition). I started with an MS in Software
Engineering, then worked on FrameMaker (Frame/Adobe), the SoftBook
Reader/eBook (SoftBook Press/Gemstar), Version Cue (Adobe), and other
stuff. UI Testing is usually under "black box", and since all three
terms (UI, testing, black box) are often seen as lesser or inferior,
many people I work with have little concept of just what it involves.

>But I have another question: what is the ideal kind of interaction design
>spec to receive, speaking from a QE/development/testing perspective? (Just
>don't tell me it's a Use Case....)

My testing goes most smoothly and has the best impact when I have the
most and the most accurate info. Testing components in isolation
isn't as effective as testing them as part of a larger package, where
feature interactions can be dealt with as well. (Although I largely
focus on UI testing, which many people would expect to result in
mostly either fuzzy usability complaints or miniscule layout bugs --
the sort which mostly never get addressed in the at-hand product
cycle -- by working in the larger package, I tend to hit the same
percentage of severe and crasher bugs as other testers, as well as
all the small stuff.)

The standard Product Life Cycle generally puts Testing very late in
the process, but since the best testing is done with full
information, QE having input earlier in the process -- during spec
review, and even before -- is massively useful. If nothing else, it
lets us understand why certain decisions were made, so we don't have
to fight with such issues when we actually get the software to test.
But usually, it allows us to give feedback on how we will test a
feature, allowing the UI team and the Dev team to recognize
weaknesses before coding them in stone.

An ideal spec to test from would include reasonably accurate
screenshot and mockups, details about each control's behavior, notes
on shortcuts and hidden features, discussion of expected feature
interactions and user workflows, and selected minutiae about
usability decisions inherent in the presentation (why bottom rather
than center aligned, like in the last release; why gray for that
dialog when all other product dialogs are blue; why are things in
this list ordered as they are). The better the detail, the less
stuff we have to assume and the better we can focus our testing.
--

----- ----- ----- ----- ----- ----- ----- ----- ----- ----- -----
Jim Drew Seattle, WA jdrew at adobe.com
http://home.earthlink.net/~rubberize/Weblog/index.html (Update: 07/20)
_______________________________________________
Interaction Design Discussion List
discuss at interactiondesigners.com
--
to change your options (unsubscribe or set digest): http://discuss.interactiondesigners.com
--
Questions: lists at interactiondesigners.com
--
Announcement Online List (discussion list members get announcements already)
http://interactiondesigners.com/announceList/
--
http://interactiondesigners.com/

Comments

29 Jul 2004 - 7:43am
pabini
2004

Allen Smith wrote: I mostly agree with all of Jim's observations about what
a good spec has, although my experience is that trying to defend every
decision in a spec is not the best way to go. I prefer to write the spec as
I want to see the product designed (functionally and visually) and then
defend any decisions on a case-by-case basis in review sessions.

***PGP I didn't hear that in what Jim wrote, but I agree with you. It's good
to document your rationale for major decisions, because in the future, you
may not be there to explain them, resulting in the product team having to go
through the same loops again. Most elements of a design are readily
understood and accepted by other team members who are equally familiar with
a product. However, during a review cycle, one always has to defend some
decisions, modify some parts of a design to balance the concerns of users
vs. developers, and clarify and add details to sections of a spec about
which engineers have specific questions. It's a collaborative process that
makes both the specs and the resulting products better.

Pabini
________________________________________

Pabini Gabriel-Petit
Principal & User Experience Architect
Spirit Softworks
www.spiritsoftworks.com

29 Jul 2004 - 12:09pm
cfmdesigns
2004

Allen Smith <al at mojofat.com> writes:

>I mostly agree with all of Jim's observations about what a good spec
>has, although my experience is that trying to defend every decision
>in a spec is not the best way to go. I prefer to write the spec as
>I want to see the product designed (functionally and visually) and
>then defend any decisions on a case-by-case basis in review sessions.

I think "defend" is too strong a word for what I was after, as it
implies a level of aggression which probably isn't there.

There's also the fact that, in practice, the spec and the product are
never the same. And further, a UI/usability/etc. spec is often even
further from the eventual reality; one of the developers I'm working
with on my current project said something to the effect of "The
Designer can put whatever he wants into the UI Spec, but what gets
into the product is ultimately my decision."

(In this case, after UI spec review, he went to code the feature and
decided -- by fiat -- that some of what was spec'ed "didn't make
sense". So he changed it to what did make sense, and now we get to
fight about the usability implications of what he implemented rather
than what the team agreed on. Which isn't to say that he isn't
technically correct in his during-coding realizations. We'll see.)

The greater concern I have is that as a product matures, those
involved may change. The usability decisions which were clear to
those who made them may not be clear to a later group -- not
necessarily wrong, but perhaps puzzling -- and if the original
designer has, say, left the company (or simply not recorded the
design decision details and can't remember them now), you're screwed,
stuck with a design which doesn't make sense.

An ideal set of specs doesn't only detail the what and the how of the
product, it details the why.
--

----- ----- ----- ----- ----- ----- ----- ----- ----- ----- -----
Jim Drew Seattle, WA jdrew at adobe.com
http://home.earthlink.net/~rubberize/Weblog/index.html (Update: 07/20)

29 Jul 2004 - 1:27pm
mojofat
2004

I think you have made a very good point. I've had to work with prima donna engineers before and it is a royal pain in the ass. I have had to stand before a group of 8 engineers and defend my use of blue hyperlinks with an orange rollover state on a white background. Seriously.

Having done some development myself though, maybe it's easier for me to discuss the product design in general and anticipate what will be problematic. However, I can say that if you have a prima donna engineer (or anybody involved in the product development, to be fair) it will ultimately not benefit the product at all. What I was imagining is a slippery slope where if we start including reasons for one thing, where do we stop? Does every single interaction point have to have an explanation as to why it's appropriate? Personally, I think the developer in your antecdote is way out of line to simply decide it doesn't make sense to him and go with something else entirely. It's not his decision, and it's extremely rude...maybe he suffers from Asperger's syndrome. If this behavior is encouraged though (even subtly by not doing anything about it), then what it leads to is people coding to whatever is the easiest thing to do instead of what is the right thing to do. I've worked in that atmosphere before, and it is the most frustrating experience. It's up to the manager or whomever is ultimately responsible to support your role and make sure things like that don't happen. Developers certainly wouldn't appreciate you doing a code review with them and challenging their coding style, so why is it acceptable to challenge the product design and ultimately make autocratic decisions about the said design? And if you have a good manager that supports your design, this behavior will likely stop the first time that developer has to throw away his/her code and redo it.

A lot of what you're speaking to I usually save in e-mail form or notes from meetings and refer to those when necessary. I think that the spec should be focused on the design, not justifying it, and that defending it...rationalizing it...whatever term you would prefer to use, is best left to a separate discussion. But, to Jim's point, a component of this may also be what work environment you find yourself. I may feel differently about including this info if I worked someplace where the engineers were second guessing my decisions and were making product design decisions on the fly like that. Fortunately though, I don't. Also, if you're working on a project as complicated and has such a deep user experience as Photoshop or any of the other many Adobe products, then that may make a difference as well. I will admit that none of the wireless applications I design are anywhere near as complicated as that. When the product does have to change b/c of development challenges (which is very common in the wireless world where I work), then we meet and discuss it and usually come to a consensus about what needs to be done. When there isn't a consensus, our boss will make the final decision...and 9 times out of 10 it will be my recommendation. Because, after all, that's why they pay me!

-al

---------- Original Message -------------
Subject: Re: [ID Discuss] Re: Design specs (Was: Design Methodology for GUI
Date: Thu, 29 Jul 2004 10:09:55 -0700
From: Jim Drew <jdrew at adobe.com>
To: discuss at interactiondesigners.com

Allen Smith <al at mojofat.com> writes:

>I mostly agree with all of Jim's observations about what a good spec
>has, although my experience is that trying to defend every decision
>in a spec is not the best way to go. I prefer to write the spec as
>I want to see the product designed (functionally and visually) and
>then defend any decisions on a case-by-case basis in review sessions.

I think "defend" is too strong a word for what I was after, as it
implies a level of aggression which probably isn't there.

There's also the fact that, in practice, the spec and the product are
never the same. And further, a UI/usability/etc. spec is often even
further from the eventual reality; one of the developers I'm working
with on my current project said something to the effect of "The
Designer can put whatever he wants into the UI Spec, but what gets
into the product is ultimately my decision."

(In this case, after UI spec review, he went to code the feature and
decided -- by fiat -- that some of what was spec'ed "didn't make
sense". So he changed it to what did make sense, and now we get to
fight about the usability implications of what he implemented rather
than what the team agreed on. Which isn't to say that he isn't
technically correct in his during-coding realizations. We'll see.)

The greater concern I have is that as a product matures, those
involved may change. The usability decisions which were clear to
those who made them may not be clear to a later group -- not
necessarily wrong, but perhaps puzzling -- and if the original
designer has, say, left the company (or simply not recorded the
design decision details and can't remember them now), you're screwed,
stuck with a design which doesn't make sense.

An ideal set of specs doesn't only detail the what and the how of the
product, it details the why.
--

----- ----- ----- ----- ----- ----- ----- ----- ----- ----- -----
Jim Drew Seattle, WA jdrew at adobe.com
http://home.earthlink.net/~rubberize/Weblog/index.html (Update: 07/20)
_______________________________________________
Interaction Design Discussion List
discuss at interactiondesigners.com
--
to change your options (unsubscribe or set digest): http://discuss.interactiondesigners.com
--
Questions: lists at interactiondesigners.com
--
Announcement Online List (discussion list members get announcements already)
http://interactiondesigners.com/announceList/
--
http://interactiondesigners.com/

29 Jul 2004 - 2:14pm
Dave Collins
2004

>There's also the fact that, in practice, the spec and the product are
>never the same. And further, a UI/usability/etc. spec is often even
>further from the eventual reality; one of the developers I'm working
>with on my current project said something to the effect of "The
>Designer can put whatever he wants into the UI Spec, but what gets
>into the product is ultimately my decision."
>
>(In this case, after UI spec review, he went to code the feature and
>decided -- by fiat -- that some of what was spec'ed "didn't make
>sense". So he changed it to what did make sense, and now we get to
>fight about the usability implications of what he implemented rather
>than what the team agreed on. Which isn't to say that he isn't
>technically correct in his during-coding realizations. We'll see.)

Not that this isn't obvious, but...
This isn't your problem. This is a problem higher up. A supervisor has
not made clear to everyone the roles and responsibilities (and the
boundaries) involved, and the teamwork required.

29 Jul 2004 - 2:39pm
cfmdesigns
2004

Dave Collins <DCollins at phoenix-interactive.com> writes:

> >There's also the fact that, in practice, the spec and the product are
>>never the same. And further, a UI/usability/etc. spec is often even
>>further from the eventual reality; one of the developers I'm working
>>with on my current project said something to the effect of "The
>>Designer can put whatever he wants into the UI Spec, but what gets
>>into the product is ultimately my decision."
>>
>>(In this case, after UI spec review, he went to code the feature and
>>decided -- by fiat -- that some of what was spec'ed "didn't make
>>sense". So he changed it to what did make sense, and now we get to
>>fight about the usability implications of what he implemented rather
>>than what the team agreed on. Which isn't to say that he isn't
>>technically correct in his during-coding realizations. We'll see.)
>
>Not that this isn't obvious, but...
>This isn't your problem. This is a problem higher up. A supervisor has
>not made clear to everyone the roles and responsibilities (and the
>boundaries) involved, and the teamwork required.

I fear I made this sound more severe an issue than it actually is. I
don't consider the developer a primadonna, and the design wasn't
drastically change (it's probably 90%-plus intact; only a few of the
behaviors and appearances got thrashed on).

But you're right to identify that there are some chain of
command/communication issue here. By no means limited to the
particular event -- or even to this single project, or the company.
I have noticed an increase in lack of process, inadequate
communication, and fiefdom in many projects and companies over the
years.

(I would tend to target that mostly at the Tech Boom/Bust, which
encouraged some small teams to say "F-ck it, we'll do things our own
way!", and maybe mix in the current Tech Offshoring trend, which has
some people restricting openness in order to assure job security.)
--

----- ----- ----- ----- ----- ----- ----- ----- ----- ----- -----
Jim Drew Seattle, WA jdrew at adobe.com
http://home.earthlink.net/~rubberize/Weblog/index.html (Update: 07/20)

30 Jul 2004 - 4:43am
Martyn Jones BSc
2004

>>Does every single interaction point have to have an explanation as to why
it's appropriate?

At present, working for a small company, I sometimes wear an Engineer's hat,
other times I focus more on best practices and storyboarding usability.
These comments might be slightly biased, as I am an Engineer first, and UI /
Usability Designer second.

When I'm playing the part of Programmer on our more complex projects, and am
not involved in the initial prototypes - I do like to see a justification
for design. More often than not, I have this justification - not through a
formal document, but because I am involved throughout the lifecycle of a
project. During initial brainstorming sessions, I can throw my concerns and
recommendations in. Those responsible for UI / Usability Design (if not
myself) can 'defend' / explain their reasoning. Most importantly I think
it's because I have a greater sense of involvement, that I am more content
to implement the design (not totally happy with this statement - don't want
to make it sound like I'll throw my toys if I'm not involved - had a better
stab at explaining it below :) ).

In cases where we work with an external design team, and I am asked to just
be a 'code-monkey' and implement - I have all sorts of issues. Entering the
project in the middle of it's development cycle, without any explanation for
why things are the way they are - I guess makes me feel as though I'm not
being given much respect. As if my opinion doesn't count. I imagine it's
mainly a physiological issue - one of power? That perhaps Engineers and
those involved in UI / Usability Design should sit at a similar level in the
'power' hierarchy of an organisation / project, but if the UI / Usability
Engineers are just dictating to the Engineers (without discussion between
the two parties), the Engineers probably feel 'power' is being taken away
from them (at least this is what I have felt, wearing my Engineer hat).

This is also part of an age old battle between techy people and arty
designers, and their possible lack of respect for each others disciplines.

For a handful of projects, we have been drafted in as the techy people for a
large localisation company. I think these projects worked particularly
well, as 'champions' from each discipline were involved throughout project
lifecycles (e.g. Chief Tester taking part in initial prototyping meetings).
I was then responsible for relaying suggestions / decisions / progress to my
development team. I think that when the time came to code, we all had a
better understanding of how / why / what to do.

Martyn

-----Original Message-----
From:
discuss-interactiondesigners.com-bounces at lists.interactiondesigners.com
[mailto:discuss-interactiondesigners.com-bounces at lists.interactiondesigners.
com] On Behalf Of Jim Drew
Sent: 29 July 2004 20:40
To: discuss at interactiondesigners.com
Subject: RE: [ID Discuss] Re: Design specs (Was: Design Methodology for GUI

Dave Collins <DCollins at phoenix-interactive.com> writes:

> >There's also the fact that, in practice, the spec and the product are
>>never the same. And further, a UI/usability/etc. spec is often even
>>further from the eventual reality; one of the developers I'm working
>>with on my current project said something to the effect of "The
>>Designer can put whatever he wants into the UI Spec, but what gets
>>into the product is ultimately my decision."
>>
>>(In this case, after UI spec review, he went to code the feature and
>>decided -- by fiat -- that some of what was spec'ed "didn't make
>>sense". So he changed it to what did make sense, and now we get to
>>fight about the usability implications of what he implemented rather
>>than what the team agreed on. Which isn't to say that he isn't
>>technically correct in his during-coding realizations. We'll see.)
>
>Not that this isn't obvious, but...
>This isn't your problem. This is a problem higher up. A supervisor has
>not made clear to everyone the roles and responsibilities (and the
>boundaries) involved, and the teamwork required.

I fear I made this sound more severe an issue than it actually is. I
don't consider the developer a primadonna, and the design wasn't
drastically change (it's probably 90%-plus intact; only a few of the
behaviors and appearances got thrashed on).

But you're right to identify that there are some chain of
command/communication issue here. By no means limited to the
particular event -- or even to this single project, or the company.
I have noticed an increase in lack of process, inadequate
communication, and fiefdom in many projects and companies over the
years.

(I would tend to target that mostly at the Tech Boom/Bust, which
encouraged some small teams to say "F-ck it, we'll do things our own
way!", and maybe mix in the current Tech Offshoring trend, which has
some people restricting openness in order to assure job security.)
--

----- ----- ----- ----- ----- ----- ----- ----- ----- ----- -----
Jim Drew Seattle, WA jdrew at adobe.com
http://home.earthlink.net/~rubberize/Weblog/index.html (Update: 07/20)
_______________________________________________
Interaction Design Discussion List
discuss at interactiondesigners.com
--
to change your options (unsubscribe or set digest):
http://discuss.interactiondesigners.com
--
Questions: lists at interactiondesigners.com
--
Announcement Online List (discussion list members get announcements already)
http://interactiondesigners.com/announceList/
--
http://interactiondesigners.com/

30 Jul 2004 - 11:45am
cfmdesigns
2004

Martyn Jones BSc <martyn at kode.co.uk> writes:

>In cases where we work with an external design team, and I am asked to just
>be a 'code-monkey' and implement - I have all sorts of issues. Entering the
>project in the middle of it's development cycle, without any explanation for
>why things are the way they are - I guess makes me feel as though I'm not
>being given much respect. As if my opinion doesn't count. I imagine it's
>mainly a physiological issue - one of power?

Power is certainly part of it, at times. A better term for it,
though, might be "ownership".

For any person on the team, there needs to be good communication of
information and roles (and agreement about such). If you are brought
in mid-project, if you are given certain responsibilities, then you
need to be given some ownership over that, as well. If your role
isn't clearly defined/communicated,that's where the conflict arises.
--

----- ----- ----- ----- ----- ----- ----- ----- ----- ----- -----
Jim Drew Seattle, WA jdrew at adobe.com
http://home.earthlink.net/~rubberize/Weblog/index.html (Update: 07/20)

31 Jul 2004 - 1:51am
pabini
2004

Jim Drew wrote:
> There's also the fact that, in practice, the spec and the product are
> never the same. And further, a UI/usability/etc. spec is often even
> further from the eventual reality; one of the developers I'm working
> with on my current project said something to the effect of "The
> Designer can put whatever he wants into the UI Spec, but what gets
> into the product is ultimately my decision."

***I think it's going too far to say that they're never the same, though
they diverge more often than they should. Sounds to me like you're
describing an engineer with a bad attitude. I always work collaboratively
with engineers to resolve differences in priorities, so what ends up in the
spec takes their constraints into account and includes whatever good ideas
they offer.

> (In this case, after UI spec review, he went to code the feature and
> decided -- by fiat -- that some of what was spec'ed "didn't make
> sense". So he changed it to what did make sense, and now we get to
> fight about the usability implications of what he implemented rather
> than what the team agreed on. Which isn't to say that he isn't
> technically correct in his during-coding realizations. We'll see.)

***That kind of thing wouldn't have been acceptable in the companies I've
worked for in recent years and just shows a sad lack of communication and
teamwork.

> The greater concern I have is that as a product matures, those
> involved may change. The usability decisions which were clear to
> those who made them may not be clear to a later group -- not
> necessarily wrong, but perhaps puzzling -- and if the original
> designer has, say, left the company (or simply not recorded the
> design decision details and can't remember them now), you're screwed,
> stuck with a design which doesn't make sense.
>
> An ideal set of specs doesn't only detail the what and the how of the
> product, it details the why.

***You're absolutely right about this. Inheriting vague specs for product
designs that are incomprehensible inevitably leads to reinventing the wheel,
wasted design and development cycles, and a lower return on a company's
investment. I think that if companies understood how costly this is to them,
they'd insist on detailed specifications. Instead, companies often sacrifice
the preparation of detailed specs to get to market quickly, or so they
think. In my experience, the more issues that are resolved during design
cycle and documented in clear specs, the faster and more efficiently
development progresses.

Syndicate content Get the feed