Functional Specs (long and getting longer)

19 Mar 2006 - 4:54pm
8 years ago
25 replies
592 reads
Peter Boersma
2003

Andrew Otwell said:
> Most web sites, and I'll bet almost no rich media are truly life-
> sustaining or have possibility of catastrophic failure consequences
> that bridges or buildings do.

I know Andrew and he can be funny at times. I am not entirely sure if he is
doing that here...I'll assume he's not.

I have designed (and built) dozens of web applications that can have
catastrophic failures, at a human or organizational scale, and up to the
country level.

Some examples are financial websites where individuals calculate if they can
pay their monthly mortgage, web applications where companies buy and sell
millions worth of phone-airtime, and governmental websites where individuals
sue others, companies file their taxes and pension funds report on their
billions worth of transactions.

And I can't be the only person doing this. Heck, someone must have designed
the machines in the emergency rooms, voting machines, ATMs, VCR's...
Alright, I'll stop there ;-)

> [..] I would
> hate to work in an environment where programmers felt unable to make
> suggestions or decisions like that. Besides, designers do the same
> thing from the perspective of business owners or product managers.

But that's exactly what specs are for! To discuss design decisions,
conditional flows, calculations and rules, written down in addition to the
screen designs that show what they'll look like, with more or less detail.

> Ok, if some rogue programmer subverts something basic about the
> product, or destroys some carefully crafted complex function, *and
> doesn't bother to tell anyone*, that's one thing.

And that's what software tests are for; they test functions, chunks of code,
entire modules, and finally the behaviour of the entire system.

In an ideal world (yes, I know), these software tests are derived from the
same requirements as our interaction designs, be they business goals,
business rules, styleguides, accessibility and usability requirements, etc.

> Usually, though,
> it's not much worse than something small that slips past you wish
> hadn't. Fix it in the next release and move on.

Try to explain that to the tax office when they say you owe them instead of
the other way around...

Peter, normally a funny guy...
--
Peter Boersma | Senior Experience Designer | Info.nl
Sint Antoniesbreestraat 16 | 1011 HB | Amsterdam, The Netherlands
p: +31-20-530 9100 | m: +31-6-15072747 | f: +31-20-530 9101
mailto:peter at peterboersma.com | http://www.peterboersma.com/blog

Comments

21 Mar 2006 - 5:56pm
cherylkimble
2005

i'm not sure i understand this thread...

it seems that we're trying to determine if writing specs is a good
idea, or if jumping right into code-ready prototyping is the answer.

i don't know anything about axure, but visio can do all that you
described. please note i am by no means a fan of visio (can you say
dynamic table of contents?), but as an ia i fight everyday to keep
prototyping out of the development process. simulations are becoming
more and more valuable for user testing and proof of concept, but
neither prototypes nor simulations can replace process. they can
certainly enhance, but never replace.

i love specs because they are the last word about the project. it is
the roadmap i leave behind so that the client or team has a thorough
understanding of why certain decisions were made and how the product
works when it ships (deploys, goes live...).

so many projects and teams flounder these days due to lack of strong
process and thorough documentation.

would you begin filming a movie without a script or a location?

best,
cheryl

At 4:29 PM -0700 3/21/06, Robert Hoekman, Jr. wrote:
>[Please voluntarily trim replies to include only relevant quoted material.]
>
>Axure rocks. I know Visio is supposed to be the holy grail for wireframing,
>but to me, it's one of the clunkiest and most awkward programs I've ever
>used. Axure makes sense, it makes it easy to get work done quickly, it feels
>light and responsive, and you can use it to generate a spec and/or a fairly
>nice interaction prototype with a few clicks. If all you want is JPGs, you
>can make those too - in one click.

21 Mar 2006 - 6:29pm
Ari
2006

lol. i'm with you there.

i inherited a very, very large project that was under development for
several months and getting no where due in large part because it had no
specs.

once i came on board, i immediately developed "commando specs" - functional
and concise but not the usual guttenberg bibles i traditionally generate and
in less than 4 weeks, we've made more progress than in the past 6 months
with a higher level of quality.

specs, especially good ones are the key to any significant project or
product.

On 3/21/06, cheryl kimble <cheryl at marginalized.com> wrote:
>
> [Please voluntarily trim replies to include only relevant quoted
> material.]
>
> i'm not sure i understand this thread...
>
> it seems that we're trying to determine if writing specs is a good
> idea, or if jumping right into code-ready prototyping is the answer.
>
> i don't know anything about axure, but visio can do all that you
> described. please note i am by no means a fan of visio (can you say
> dynamic table of contents?), but as an ia i fight everyday to keep
> prototyping out of the development process. simulations are becoming
> more and more valuable for user testing and proof of concept, but
> neither prototypes nor simulations can replace process. they can
> certainly enhance, but never replace.
>
> i love specs because they are the last word about the project. it is
> the roadmap i leave behind so that the client or team has a thorough
> understanding of why certain decisions were made and how the product
> works when it ships (deploys, goes live...).
>
> so many projects and teams flounder these days due to lack of strong
> process and thorough documentation.
>
> would you begin filming a movie without a script or a location?
>
> best,
> cheryl
>
>
> At 4:29 PM -0700 3/21/06, Robert Hoekman, Jr. wrote:
> >[Please voluntarily trim replies to include only relevant quoted
> material.]
> >
> >Axure rocks. I know Visio is supposed to be the holy grail for
> wireframing,
> >but to me, it's one of the clunkiest and most awkward programs I've ever
> >used. Axure makes sense, it makes it easy to get work done quickly, it
> feels
> >light and responsive, and you can use it to generate a spec and/or a
> fairly
> >nice interaction prototype with a few clicks. If all you want is JPGs,
> you
> >can make those too - in one click.
> ________________________________________________________________
> Welcome to the Interaction Design Association (IxDA)!
> To post to this list ....... discuss at ixda.org
> List Guidelines ............ http://listguide.ixda.org/
> List Help .................. http://listhelp.ixda.org/
> (Un)Subscription Options ... http://subscription-options.ixda.org/
> Announcements List ......... http://subscribe-announce.ixda.org/
> Questions .................. lists at ixda.org
> Home ....................... http://ixda.org/
> Resource Library ........... http://resources.ixda.org
>

--
------------------------------------------------
Ari Feldman
Executive Producer, Heavy Inc.
www.heavy.com

21 Mar 2006 - 9:07pm
Robert Hoekman, Jr.
2005

> ... as an ia i fight everyday to keep
> prototyping out of the development process.

I don't think anyone here is denouncing process entirely in favor of
prototypes, and prototypes definitely have their place. Sometimes it's
just better to show it than explain it. A prototype leaves a lot less
room for interpretation than the written word. Often, a description -
even a very good one - is met with several rounds of back-and-forth
email, questions, clarifications, revisions to the spec, etc. A
prototype prevents most of this, providing it's good enough to
accurately represent what needs to be built.

> i love specs because they are the last word about the project. it is
> the roadmap i leave behind so that the client or team has a thorough
> understanding of why certain decisions were made and how the product
> works when it ships (deploys, goes live...).

Actually, programmers have the last word. And "leaving behind a
roadmap" is only going to help ensure they (at least partly) ignore
your hard work.

-r-

21 Mar 2006 - 9:52pm
cherylkimble
2005

> Sometimes it's
>just better to show it than explain it.

i agree and that, in my opinion, is what the wireframes are for.
sitemap, wireframes, specs/simulation, development.

these days it seems that everyone wants documentation but no one has
the patience to listen to the presentation. they make a lot of
assumptions without listening and then decide since they can't
understand what's going on, they need to build a prototype.

"i won't know what i want until i see it"

well, how about trusting your team and giving them the information
they need? that works.

>
>Actually, programmers have the last word. And "leaving behind a
>roadmap" is only going to help ensure they (at least partly) ignore
>your hard work.
>
>-r-

ideally, the spec should be the last word and visual designers, ia's
and techs review them together to make sure they are correct and meet
the needs of the project before going into the build. i've never
worked with an engineer who preferred to "wing it". they are always
grateful to have it all laid out for them.

best,

cheryl

21 Mar 2006 - 10:45pm
Robert Hoekman, Jr.
2005

> well, how about trusting your team and giving them the information
> they need? that works.

I don't mean to imply this is a trust issue. It's just about closing
the communication gap. Words can take you very far in the effort to
explain what you intend for an interaction, but a prototype can take
you further and can even entirely eliminate the possibility of
misinterpretations. I'm not in a position to mandate anything - I can
only recommend - and prototypes help communicate what I want in a way
that's more efficient for developers.

> i've never
> worked with an engineer who preferred to "wing it". they are always
> grateful to have it all laid out for them.

I concur, but programmers still have the last word, because they - and
only they - have ultimate control over how things get implemented or
whether they get implemented at all.

Interesting debate. This list is such a great resource.

-r-

22 Mar 2006 - 12:31am
mojofat
2004

I submit that whoever is writing the check has the last word. =)

-al

On Mar 21, 2006, at 8:45 PM, Robert Hoekman, Jr. wrote:

> [Please voluntarily trim replies to include only relevant quoted
> material.]
>
>> well, how about trusting your team and giving them the information
>> they need? that works.
>
> I don't mean to imply this is a trust issue. It's just about closing
> the communication gap. Words can take you very far in the effort to
> explain what you intend for an interaction, but a prototype can take
> you further and can even entirely eliminate the possibility of
> misinterpretations. I'm not in a position to mandate anything - I can
> only recommend - and prototypes help communicate what I want in a way
> that's more efficient for developers.
>
>> i've never
>> worked with an engineer who preferred to "wing it". they are always
>> grateful to have it all laid out for them.
>
> I concur, but programmers still have the last word, because they - and
> only they - have ultimate control over how things get implemented or
> whether they get implemented at all.
>
> Interesting debate. This list is such a great resource.
>
> -r-
> ________________________________________________________________
> Welcome to the Interaction Design Association (IxDA)!
> To post to this list ....... discuss at ixda.org
> List Guidelines ............ http://listguide.ixda.org/
> List Help .................. http://listhelp.ixda.org/
> (Un)Subscription Options ... http://subscription-options.ixda.org/
> Announcements List ......... http://subscribe-announce.ixda.org/
> Questions .................. lists at ixda.org
> Home ....................... http://ixda.org/
> Resource Library ........... http://resources.ixda.org
>
>

22 Mar 2006 - 1:46pm
Katie Albers
2005

At 9:39 AM -0500 3/22/06, Bernie Monette [c] wrote:
>Have you ever been to a meeting where you ask: does everyone understand
>this? And everyone agrees,nods their heads, and then goes off and does
>whatever they want? Or when they don't understand something just make do and
>hope for the best? To me, since it is usually my estimate that is on the
>line, this is scary.

I've been on both sides of this phenomenon and I've found that what
happens is not that people don't understand, but their understanding
of what you were talking about is different. People have different
frameworks, different understandings of words, different
understandings of process. So, everyone understood everything said,
but they all understood it to mean different things. However, no one
has the tools to realize that you meant something *else*

It's no good to say "don't assume anything", because they aren't
assuming. They *know* that (for example) a wireframe is basically a
screen layout with the locations of all the elements clearly
specified and the points and results of interactivity clearly laid
out. Now, some of us read that and thought "yeah" and others read it
and thought "that's getting *way* into visual design." Both these
groups if asked to produce a wireframe would confidently go out and
produce one, but only one group would even approach producing the
expected items.

It's been my experience that most of these failures in the process
are the result of miscommunication on such a deep level that it isn't
even possible for the participants to identify that there has been a
misunderstanding. That's one of the reasons why iterative processes
work so much better than waterfall processes the more elements you
add to the equation. Cascading processes work fairly well when you
can say "this must do this, name your variables using this scheme,
this input has to happen, this function must be performed, this
output must occur" It's relatively easy to understand a single
problem around a single constellation of identifiable issues. When
you get into areas where multiple sets of criteria are critical, it's
much less obvious. Especially when further complicated by the fact
that so many individual's backgrounds are different.

People in interactive fields tend to see themselves as User
Experience specialists who came out of programming backgrounds or IxD
people who have extensive visual design experience, or myriad
variations. Each of them has their understanding of the field shaped
by that background experience and they incorporate and use pieces of
that background, including the IxD field in general on the basis of
that experience. It makes it very hard to use vocabulary to achieve
understanding.

Over the years, I've found that frequent meetings in a room with a
huge whiteboard where everybody has a pen and can contribute produce
the most reliable results in understanding. The physical presence of
the whiteboard is critical because many of the participants need the
kinetic experience to reinforce their understanding. I also let
people write notes on the board, as well as drawing (some people just
do not understand things visually. they're text based. and you can't
change that). If you don't have a printing or transmitting
whiteboard, then take a high res photo and either scan it or download
it.

There will still be some misunderstandings, but I find that this
eliminates a substantial percentage. Of course, you will still have
some people who decided that their way was better. Sometimes they
will be right. If they're right, I tell them "great, you're right.
but you need to let me know so that I can change everyone's
destination and the documentation." and I find that the sense of
ownership cuts down on people doing unexpected things that are wrong.
When they do...that's a whole different issue.

The functional spec is then pictures with call-outs on any issues
that need to be attended to. Changes during the project are noted,
but only the most recent specs are shown in the document.

And this is now way too long

Katie

27 Mar 2006 - 9:40pm
cfmdesigns
2004

cheryl kimble <cheryl at marginalized.com> writes:

>i love specs because they are the last word about the project. it is
>the roadmap i leave behind so that the client or team has a thorough
>understanding of why certain decisions were made and how the product
>works when it ships (deploys, goes live...).

Frankly, I think that the "don't write specs" crowd are the ones who
don't want to be answerable for their decisions or to the schedule.

As a UI tester, I hate it when I don't have adequate specs to do my
planning from. Because without those specs, I get software "thrown
over the fence": here, test this. I have no means of scoping my
schedule, I can't do any planning until the software is far enough
along to give to me, I have to divine the developer's intent, and I
can't act as as a "conscience" early in the process to make sure that
good UI "stuff" gets built in.

(You know, the small things: keyboard shortcuts, dialog tabbing,
controls working consistently, Section 508 and XP/Vista logo
compliance, color choice, liquid layout... basically all the
subtleties which developers tend to forget in order to get to the
meaty, interesting, big features, but which make the difference
between good software and hackware, and which have to be planned for
at the beginning of there's no time to put them in later.)

Every time I've dealt with unspec'ed or underspec'ed software, it's
ended up being a big fight and headache for everyone. The very best
situations I've been in had MRDs, specs, reviews with all the teams,
ECOs, and all of it tied into an index where you could find the info
you needed and the persons responsible. Took more time up front, but
reduced the stresses later on massively.
--

----- ----- ----- ----- ----- ----- ----- ----- ----- ----- -----
Jim Drew Seattle, WA cfmdesigns at earthlink.net
http://home.earthlink.net/~rubberize/Weblog/index.html (Update: 3/24)
(Subject: Musical Commentary: The Wedding Singer)

28 Mar 2006 - 4:49am
Rich Holman
2005

Although I swear by comprehensive specs, I do sometimes wonder how useful
they are to others.

I know that when I create a 40 page document outlining a new system, about
the only person to read it fully will be myself. It's almost become a
paradoxical situation, I have to write a spec otherwise I won't be able to
point out errors in the eventual system. If I don't produce a spec then I
can't tell the developers that they have not delivered correctly on the
system.

So in that sense I do see that getting rid of specs won't necessarily
produce vastly different systems if the developer has no intention of
following the spec completely. However from my perspective, there would be
no way of analysing the success of a system without a spec.

For me, the biggest successes have come from a regular 30 minute meetings
with the developers (occasionally biting my lip when one of them suggests it
would be useful to document these requirements).

I accept that a 40 page document is not the ideal bed-reading material so
just try and use the spec as a guide and introduce sections of it into face
to face meetings.
--
Rich Holman

28 Mar 2006 - 8:54am
jrrogan
2005

(wrote this for another post but is more relevant here)

Big Documentation to Prototypes and back again – A real world tale of two
companies:

Prototype to Big Documentation:

I'm working on an agile scrum project for a new application, where my
deliverables changed from Prototypes, with work flow/site flow maps, to
fully documented screens, matched with Reqs, Use Cases, and Visio states and
transition flows, (big document).

Prototypes were not explicit for consumers to get the big picture of the
product and how the features fit in.

Certain developers knew specific features, other developers didn't.
Engineering handoffs were a nightmare, developers, QA and BA's had to
completely learn the prototype with each major change, and not miss
anything. It was incredibly cumbersome, and nobody was happy.

Now that I'm documenting screen shots, QA is definitely happy, Engineering
knows what's going on and has no issue with handing off work to other
engineers or off shoring; the world is a happy place.

Big documentation to Prototype:

Two contracts earlier I was creating big documents for an application which
was 1 year into design/dev, engineering wasn't happy.

Documentation included screen callouts, flows, related Use Cases, User
stores, (big documents). Engineers indicated flows, states and transitions
weren't explicit enough, the document hid relationships and made design
confusing. We moved to Prototyping and everyone was very happy.

The moral - Possibly just change itself is responsible for productivity:

In business process reengineering productivity tends to increase with
change. Possibly just changing a team's design deliverables increases
productivity period.

PS:

I definitely feel that an interface that is well known by engineers,
business and QA lends itself much better to just prototyping. A completely
new interface is better documented explicitly and obviously.

Rich

28 Mar 2006 - 10:00am
Robert Hoekman, Jr.
2005

> Frankly, I think that the "don't write specs" crowd are the ones who
> don't want to be answerable for their decisions or to the schedule.

>From what I've seen, they're mostly people building apps for themselves, or
building apps with such a small team that it's just not necessary. My
company couldn't really get away with this. too many people need to know
what's going on to live without some form of documentation, and each IxD is
working on too many different apps to build out our own HTML.

As a UI tester, I hate it when I don't have adequate specs to do my
> planning from. Because without those specs, I get software "thrown
> over the fence": here, test this.

That's a key point right there. You're a QA tester. QA absolutely has to
know how the thing should work, or testing is just random.

Tell me, though - what do you really need in a spec to do your job? I'd like
to believe the most effective specs are those that contain screenshots and
use cases (use cases in the sense that I describe step-by-step interactions
and list out the exceptions the same way). Screenshots show what screen to
look at and give you a reference point for the use cases, and the use cases
describe what the screenshot can't, which is how the application is supposed
to react to each manipulation of it by the user.

Do you need anything else in a spec? If so, what? And why? I'm interested in
seeing how others handle this.

-r-

28 Mar 2006 - 10:53am
jrrogan
2005

You wrote:

> Tell me, though - what do you really need in a spec to do your job? I'd
> like
> to believe the most effective specs are those that contain screenshots and
> use cases (use cases in the sense that I describe step-by-step
> interactions
> and list out the exceptions the same way). Screenshots show what screen to
> look at and give you a reference point for the use cases, and the use
> cases
> describe what the screenshot can't, which is how the application is
> supposed
> to react to each manipulation of it by the user.
>

I would generally put use cases as a reference to the functionality, which
would not necessarily represent actual product flows.

Use Cases, with main and alternate flows, represent functionality and user
intention, but may not be explicitly mapped to UI interaction, for good
reason.

A use case should describe what not how, allowing for flexible UI solutions
separated from business requirements.

Product/Widget descriptions and may use modified use cases in detail
interaction that maps to actual flows.

You wrote:

> Tell me, though - what do you really need in a spec to do your job? I'd
> like
> to believe the most effective specs are those that contain screenshots and
> use cases (use cases in the sense that I describe step-by-step
> interactions
> and list out the exceptions the same way). Screenshots show what screen to
> look at and give you a reference point for the use cases, and the use
> cases
> describe what the screenshot can't, which is how the application is
> supposed
> to react to each manipulation of it by the user.
>
>

28 Mar 2006 - 12:20pm
Robert Hoekman, Jr.
2005

> A use case should describe what not how, allowing for flexible UI
> solutions
> separated from business requirements.

Interesting. I started writing use cases as a programmer, so the ones I
write tend to detail the actual interaction. They're not abstract at all -
they're as granular as I can make them and include tech notes. The
developers here love it. They really appreciate having the short, concise
details of how something is supposed to work accompanied by screens of how
it looks at each stage.

Thanks for the input ...

-r-

28 Mar 2006 - 12:47pm
Josh Seiden
2003

"Use cases" mean many things to many people.

The distinction in this case is between "concrete" use
cases and "abstract" use cases. (I believe that this
is Larry Constantine's idea--correction welcome...)

Abstract use cases describe the problem, do not
discuss the solution, and can be supported with a
variety of design solutions.

Concrete use cases describe the solution.

One is not better than the other--they're just
different tools for different parts of the design
process.

JS

--- "Robert Hoekman, Jr." <mmbeta at gmail.com> wrote:

> [Please voluntarily trim replies to include only
> relevant quoted material.]
>
> > A use case should describe what not how, allowing
> for flexible UI
> > solutions
> > separated from business requirements.
>
>
> Interesting. I started writing use cases as a
> programmer, so the ones I
> write tend to detail the actual interaction. They're
> not abstract at all -
> they're as granular as I can make them and include
> tech notes. The
> developers here love it. They really appreciate
> having the short, concise
> details of how something is supposed to work
> accompanied by screens of how
> it looks at each stage.
>
> Thanks for the input ...
>
> -r-

28 Mar 2006 - 2:21pm
Oleh Kovalchuke
2006

>The distinction ... is between "concrete" use
> cases and "abstract" use cases.

Yep, one case emphasizes user goals, another tasks. Both are fuzzy
categories, of course. Both are important and represented in the final
product [another fuzzy category].
--
Oleh Kovalchuke

28 Mar 2006 - 2:56pm
Jenifer Tidwell
2003

Agreed -- they are different tools for different phases of the process. In
my current project, in fact, we've taken particular care to distinguish
these two kinds of use cases.

When you're first starting to figure out the space of possible solutions,
it's most helpful to have use cases that very concretely define the
"problem:" the user's activities, tasks, data, and context. But they're
very noncommittal on how your design might solve it -- any number of
specific designs might work. These kinds of use cases make terrific tools
for brainstorming, for prioritizing the problems to be solved, and for
communicating the essence of the design problem to management (and others).

Later in the process, you can use the same use cases to describe your actual
design solutions. Here, excruciating details about the design itself are
valuable for the reasons Robert and others have mentioned -- communication
to development and QA, building prototypes, writing specs, etc.

- Jenifer

---------------------------------------
Jenifer Tidwell
jenifer.tidwell at gmail.com
http://designinginterfaces.com
http://jtidwell.net

On 3/28/06, Josh Seiden <joshseiden at yahoo.com> wrote:
>
> [Please voluntarily trim replies to include only relevant quoted
> material.]
>
> "Use cases" mean many things to many people.
>
> The distinction in this case is between "concrete" use
> cases and "abstract" use cases. (I believe that this
> is Larry Constantine's idea--correction welcome...)
>
> Abstract use cases describe the problem, do not
> discuss the solution, and can be supported with a
> variety of design solutions.
>
> Concrete use cases describe the solution.
>
> One is not better than the other--they're just
> different tools for different parts of the design
> process.
>
> JS
>
> --- "Robert Hoekman, Jr." <mmbeta at gmail.com> wrote:
>
> > [Please voluntarily trim replies to include only
> > relevant quoted material.]
> >
> > > A use case should describe what not how, allowing
> > for flexible UI
> > > solutions
> > > separated from business requirements.
> >
> >
> > Interesting. I started writing use cases as a
> > programmer, so the ones I
> > write tend to detail the actual interaction. They're
> > not abstract at all -
> > they're as granular as I can make them and include
> > tech notes. The
> > developers here love it. They really appreciate
> > having the short, concise
> > details of how something is supposed to work
> > accompanied by screens of how
> > it looks at each stage.
> >
> > Thanks for the input ...
> >
> > -r-
>
>

28 Mar 2006 - 11:22pm
cfmdesigns
2004

"Robert Hoekman, Jr." <mmbeta at gmail.com> writes:

>Frankly, I think that the "don't write specs" crowd are the ones who
>don't want to be answerable for their decisions or to the schedule.
>
>From what I've seen, they're mostly people building apps for
>themselves, or building apps with such a small team that it's just
>not necessary.

I wish that were the case, but I've seen examples at largish
companies where there is a reluctance to create specs, sometimes by
individuals and sometimes by the entire team (which I think may be
carryover/coverover for high-placed individuals on the team).

>As a UI tester, I hate it when I don't have adequate specs to do my
>planning from. Because without those specs, I get software "thrown
>over the fence": here, test this.
>
>That's a key point right there. You're a QA tester. QA absolutely
>has to know how the thing should work, or testing is just random.

"Test it and let us know if it doesn't work" is a phrase I've been
given. With isolated items, that can be fine -- should it do this
way or that, test it and let us know if you think what it does should
change -- but it's lousy in the general case.

>Tell me, though - what do you really need in a spec to do your job?
>I'd like to believe the most effective specs are those that contain
>screenshots and use cases (use cases in the sense that I describe
>step-by-step interactions and list out the exceptions the same way).
>Screenshots show what screen to look at and give you a reference
>point for the use cases, and the use cases describe what the
>screenshot can't, which is how the application is supposed to react
>to each manipulation of it by the user.
>
>Do you need anything else in a spec? If so, what? And why? I'm
>interested in seeing how others handle this.

Mostly, I need evidence that the feature interactions and
implications have been thought through.

What the final version of the feature is, both in terms of behaviors
and especially with UI specifics, will always drift from the spec,
but should not drift far. Teams usually can't afford the time to
retroactively update all the fine details.

I like to see screenshots, mockups, or wireframes which reflect the
product reality with a certain degree of accuracy, and which call out
the place known to diverge. I like them to show whatever level of
detail is available in the UI controls placement, especially relative
to other controls. (This sits above this, those two stay aligned,
there's a buffer space here.)

I like to see evidence of decisions and tradeoffs and inapplicable
considerations. Why is the control blue and the order reverse alpha,
and why didn't we put in a Cancel button? Part of that is just proof
that there was through rather than randomness behind the decisions,
but mostly because it explains thought processes and heads off
questions.

Ultimately, I need a document which offers What and How, and allows
the discussion of Why. If I don't have the first two, then I can't
get to the latter, and thus I can't understand what's going on and
properly advocate for the end user.
--

----- ----- ----- ----- ----- ----- ----- ----- ----- ----- -----
Jim Drew Seattle, WA cfmdesigns at earthlink.net
http://home.earthlink.net/~rubberize/Weblog/index.html (Update: 3/27)
(Subject: Torture: It's in the Blood, and the Body, Broken for You)

29 Mar 2006 - 6:31am
vutpakdi
2003

Jim Drew / CFM Designs wrote:
> [Please voluntarily trim replies to include only relevant quoted material.]
>
> cheryl kimble <cheryl at marginalized.com> writes:
>
>
>> i love specs because they are the last word about the project. it is
>> the roadmap i leave behind so that the client or team has a thorough
>> understanding of why certain decisions were made and how the product
>> works when it ships (deploys, goes live...).
>>
>
> Frankly, I think that the "don't write specs" crowd are the ones who
> don't want to be answerable for their decisions or to the schedule.
>
>

I think that it really depends on the designer, the team, the process
that they use, and everyone's relationship to each other. I adapt what
I do to match the situation. I have one team that absolutely loved the
big document design that I did last year, so much so that they were
eager to do some horse trading in order to get me back for a similar
effort this year. They said that they loved having a clear picture,
with descriptions, of what they were supposed to build. The process
also helped the team explore requirements as well as how things were
supposed to work internally.

On the other hand, I also work with teams where a light touch with
constant tweaks of what they do and very little or light documentation
works best.

As with so many things, I think that it just depends... :-)

Ron

29 Mar 2006 - 6:54am
hj
2005

> -----Original Message-----
> From: Ron Vutpakdi
>
> I think that it really depends on the designer, the team, the
> process that they use, and everyone's relationship to each
> other.

And of course, timescales. 'My' developers like the full detail specs, but they also want them 'now' and can't wait for them to be put together.

Finding a way to spec things in detail in extremely short timescales is difficult.

- h

29 Mar 2006 - 1:00pm
Daphne Ogle
2005

>
> "Robert Hoekman, Jr." <mmbeta at gmail.com> writes:
>
>> Frankly, I think that the "don't write specs" crowd are the ones who
>> don't want to be answerable for their decisions or to the schedule.
>>
>> From what I've seen, they're mostly people building apps for
>> themselves, or building apps with such a small team that it's just
>> not necessary.
Actually I've worked on fairly large teams in an agile development
environment where not having specs worked very well...or maybe it's
more a matter of the format and timing. We (the user experience
designers....called High-tech anthropoligists at this particular
organization) delivered pieces of the puzzle for each iteration. The
pieces were use cases scheduled for each iteration. And for each we
delivered mock-ups along with story cards that described the
interaction. So we still had something to test against and we were
testing early and often. The main benefit is that both the design
team and the development team learned a ton in each iteration that we
were able to utilize on the next.

I've attached a couple white papers from that company related to this
topic. "Adapting..." touches on no specs while "The Nature of the
Team..." describes the team make-up that allowed those processes to
work.

Daphne Ogle
Interaction Designer
Educational Technologies Services
daphne at media.berkeley.edu
cell (510)847-0308

-------------- next part --------------
A non-text attachment was scrubbed...
Name: Adapting Projects to an Accelerated Society.pdf
Type: application/pdf
Size: 436308 bytes
Desc: not available
Url : /pipermail/discuss-interactiondesigners.com/attachments/20060329/af24f4b8/AdaptingProjectstoanAcceleratedSociety-0001.pdf
-------------- next part --------------
A non-text attachment was scrubbed...
Name: The%20Nature%20of%20the%20Team.pdf
Type: application/pdf
Size: 4723037 bytes
Desc: not available
Url : /pipermail/discuss-interactiondesigners.com/attachments/20060329/af24f4b8/The20Nature20of20the20Team-0001.pdf
-------------- next part --------------

29 Mar 2006 - 3:38pm
stauciuc
2006

On 3/29/06, Daphne Ogle <daphne at media.berkeley.edu> wrote:
>
> [Please voluntarily trim replies to include only relevant quoted
> material.]
>
>
>
> >
> > "Robert Hoekman, Jr." <mmbeta at gmail.com> writes:
> >
> >> Frankly, I think that the "don't write specs" crowd are the ones who
> >> don't want to be answerable for their decisions or to the schedule.
> >>
> >> From what I've seen, they're mostly people building apps for
> >> themselves, or building apps with such a small team that it's just
> >> not necessary.
> Actually I've worked on fairly large teams in an agile development
> environment where not having specs worked very well...or maybe it's
> more a matter of the format and timing. We (the user experience
> designers....called High-tech anthropoligists at this particular
> organization) delivered pieces of the puzzle for each iteration. The
> pieces were use cases scheduled for each iteration. And for each we
> delivered mock-ups along with story cards that described the
> interaction. So we still had something to test against and we were
> testing early and often. The main benefit is that both the design
> team and the development team learned a ton in each iteration that we
> were able to utilize on the next.
>
> I've attached a couple white papers from that company related to this
> topic. "Adapting..." touches on no specs while "The Nature of the
> Team..." describes the team make-up that allowed those processes to
> work.
>
> Daphne Ogle
> Interaction Designer
> Educational Technologies Services
> daphne at media.berkeley.edu
> cell (510)847-0308
>
>
>
>
>
>
>
> ________________________________________________________________
> Welcome to the Interaction Design Association (IxDA)!
> To post to this list ....... discuss at ixda.org
> List Guidelines ............ http://listguide.ixda.org/
> List Help .................. http://listhelp.ixda.org/
> (Un)Subscription Options ... http://subscription-options.ixda.org/
> Announcements List ......... http://subscribe-announce.ixda.org/
> Questions .................. lists at ixda.org
> Home ....................... http://ixda.org/
> Resource Library ........... http://resources.ixda.org
>
>
>
This is very interesting!

Thanks for sharing

--
Sebi

1 Apr 2006 - 7:37pm
dszuc
2005

Good discussion!

It may not be possible to have 1 document to satisfy all the different
audience types, but perhaps *different flavours* of the same document as it
moves forward.

For example:

Critical application flows documented driven by key tasks & business goals
as:

* Spec 1 - Screens & *high level* design memos to help business stakeholders
& end users understand what is being built - this may also be a PowerPoint
presentation indicating behaviours (paper prototype usability test)

* Spec 2 - Screens & *detailed* design memos to help designers mock up a
semi working prototype to show business stakeholders & end users (semi
working prototype usability test)

* Spec 3 - Screens & detailed design memos & *technical specs* (how this
will all work with existing and/or new systems) (working prototype usability
test)

Each spec should ideally flow into the next and provide placeholders for
input from each stakeholder (IT, business, users). You can schedule
design/review meetings between each version of the spec with end users, as
you move towards lockdown the system for development.

A company that can define these design, review, spec cycles in a rapid but
effective way, will do very well! Which companies do this well now? (with
the push to innovate and get these products to market)

Rgds,

Daniel Szuc
Principal Usability Consultant
Apogee Usability Asia Ltd
www.apogeehk.com
'Usability in Asia'

-----Original Message-----
From: discuss-bounces at lists.interactiondesigners.com
[mailto:discuss-bounces at lists.interactiondesigners.com] On Behalf Of Robert
Hoekman, Jr.
Sent: Wednesday, March 29, 2006 2:20 AM
To: Rich Rogan
Cc: discuss at ixda.org
Subject: Re: [IxDA Discuss] Functional Specs (long and getting longer)

[Please voluntarily trim replies to include only relevant quoted material.]

> A use case should describe what not how, allowing for flexible UI
> solutions separated from business requirements.

Interesting. I started writing use cases as a programmer, so the ones I
write tend to detail the actual interaction. They're not abstract at all -
they're as granular as I can make them and include tech notes. The
developers here love it. They really appreciate having the short, concise
details of how something is supposed to work accompanied by screens of how
it looks at each stage.

Thanks for the input ...

-r-
________________________________________________________________
Welcome to the Interaction Design Association (IxDA)!
To post to this list ....... discuss at ixda.org
List Guidelines ............ http://listguide.ixda.org/
List Help .................. http://listhelp.ixda.org/
(Un)Subscription Options ... http://subscription-options.ixda.org/
Announcements List ......... http://subscribe-announce.ixda.org/
Questions .................. lists at ixda.org
Home ....................... http://ixda.org/
Resource Library ........... http://resources.ixda.org

1 Apr 2006 - 9:52pm
John Vaughan - ...
2004

Daniel Szuc nails it

> It may not be possible to have 1 document to satisfy all the different
> audience types, but perhaps *different flavours* of the same document as
> it
> moves forward.

I might describe the document profiles and their audiences slightly
differently than Dan, but a "living document" that morphs is a great
technique. Provides consistency and continuity, as well as flexibility.

0 - Screen captures from legacy system w/ functional analysis - a
"preliminary site evaluation" or "legacy inventory"
1 - Overview & business case for highest level decisionmakers
1a - Overview & feature set w/screenshots becomes marketing & rollout
collateral
2 - Screenshots w/ "design spec" for business stakeholders, designers &
usability testbed
2a - Screenshots w/ design spec/functional spec becomes documentation,
training & online help
3 - Screenshots w/ "functional tech spec" for coders & QA

John Vaughan
The Communication Studio LLC
email: vaughan1 at optonline.net
website: http://www.jcvtcs.com

2 Apr 2006 - 9:50am
Robert Hoekman, Jr.
2005

I've thought about doing this myself. Different people need different
information about what is being built, so I think creating several
different docs, each for a specific group, would be the best way to
go, so no one is overloaded with info they don't need.

-r-

On 4/1/06, Daniel Szuc <dszuc at apogeehk.com> wrote:
> [Please voluntarily trim replies to include only relevant quoted material.]
>
> Good discussion!
>
> It may not be possible to have 1 document to satisfy all the different
> audience types, but perhaps *different flavours* of the same document as it
> moves forward.
>
> For example:
>
> Critical application flows documented driven by key tasks & business goals
> as:
>
> * Spec 1 - Screens & *high level* design memos to help business stakeholders
> & end users understand what is being built - this may also be a PowerPoint
> presentation indicating behaviours (paper prototype usability test)
>
> * Spec 2 - Screens & *detailed* design memos to help designers mock up a
> semi working prototype to show business stakeholders & end users (semi
> working prototype usability test)
>
> * Spec 3 - Screens & detailed design memos & *technical specs* (how this
> will all work with existing and/or new systems) (working prototype usability
> test)
>
> Each spec should ideally flow into the next and provide placeholders for
> input from each stakeholder (IT, business, users). You can schedule
> design/review meetings between each version of the spec with end users, as
> you move towards lockdown the system for development.
>
> A company that can define these design, review, spec cycles in a rapid but
> effective way, will do very well! Which companies do this well now? (with
> the push to innovate and get these products to market)
>
> Rgds,
>
> Daniel Szuc
> Principal Usability Consultant
> Apogee Usability Asia Ltd
> www.apogeehk.com
> 'Usability in Asia'
>
> -----Original Message-----
> From: discuss-bounces at lists.interactiondesigners.com
> [mailto:discuss-bounces at lists.interactiondesigners.com] On Behalf Of Robert
> Hoekman, Jr.
> Sent: Wednesday, March 29, 2006 2:20 AM
> To: Rich Rogan
> Cc: discuss at ixda.org
> Subject: Re: [IxDA Discuss] Functional Specs (long and getting longer)
>
>
> [Please voluntarily trim replies to include only relevant quoted material.]
>
> > A use case should describe what not how, allowing for flexible UI
> > solutions separated from business requirements.
>
>
> Interesting. I started writing use cases as a programmer, so the ones I
> write tend to detail the actual interaction. They're not abstract at all -
> they're as granular as I can make them and include tech notes. The
> developers here love it. They really appreciate having the short, concise
> details of how something is supposed to work accompanied by screens of how
> it looks at each stage.
>
> Thanks for the input ...
>
> -r-
> ________________________________________________________________
> Welcome to the Interaction Design Association (IxDA)!
> To post to this list ....... discuss at ixda.org
> List Guidelines ............ http://listguide.ixda.org/
> List Help .................. http://listhelp.ixda.org/
> (Un)Subscription Options ... http://subscription-options.ixda.org/
> Announcements List ......... http://subscribe-announce.ixda.org/
> Questions .................. lists at ixda.org
> Home ....................... http://ixda.org/
> Resource Library ........... http://resources.ixda.org
>
> ________________________________________________________________
> Welcome to the Interaction Design Association (IxDA)!
> To post to this list ....... discuss at ixda.org
> List Guidelines ............ http://listguide.ixda.org/
> List Help .................. http://listhelp.ixda.org/
> (Un)Subscription Options ... http://subscription-options.ixda.org/
> Announcements List ......... http://subscribe-announce.ixda.org/
> Questions .................. lists at ixda.org
> Home ....................... http://ixda.org/
> Resource Library ........... http://resources.ixda.org
>

2 Apr 2006 - 12:31pm
Stuart Gibbons
2006

On 4/2/06, Robert Hoekman, Jr. <mmbeta at gmail.com> wrote:
> [Please voluntarily trim replies to include only relevant quoted material.]
>
> I've thought about doing this myself. Different people need different
> information about what is being built, so I think creating several
> different docs, each for a specific group, would be the best way to
> go, so no one is overloaded with info they don't need.
>

Funnily enough I've just been building my own system in Word to do
something like this. I was going to transfer requirements docs to a
wiki but still needed to get the information out again into
client-facing documents, so this acts like a Word wiki (except I'm the
only editor at the moment!).

It relies on two Word features:
- Hyperlinks to link between different documents.
- Included text fields to pull together information from individual docs.

I'm still working on what information goes in which document, and I
can't say whether it's going to be successful or not yet (the main
problem I was trying to overcome was that one big doc took too long to
update and changes and decisions were treated by developers as
software bugs rather than changes to the spec), but it currently works
something like this:

- Each web page has its own document which is targetted at developers.
It has a wireframe, copy, and interactions (clicking on this button
does X), but also any implementation guidelines/technical notes. The
interactions section has hyperlinks to other documents so you can
navigate through the pages as you would in the system. The set of page
specs makes a kind of prototype that is my living spec and is quick to
update.

- A new feature, new requirement, major change request etc has its own
analysis document. This is my 'workspace' which is targetted at
internal management/other designers, where I note design constraints,
business requirements, options, decisions taken, design rationale etc.
The stuff which our developers consider "guff" I've been told! This
analysis doc has hyperlinks to new or modified web page specs. The web
page specs have hyperlinks back to the analysis documents in the
document revision history.

This set up lets developers and managers view the info they want but
still be able to link to related documents to see where decisions have
come from or how decisions manifest etc.

When I then need to build customer documents containing information
from the individual specs I do this by marking the information in the
specs using Word bookmarks, then including that bookmark text in the
customer doc using an INCLUDETEXT field.

Example: I used to have one big (100 page) func spec detailing every
page, the copy on each page, and the interactions, with links between
the different sections of the spec. Now the func spec is only really
3-4 pages long because its just a set of pointers to sections of the
individual page specs. These sections are marked in each page spec
with a bookmark called 'UISpec', and only the
wireframe/copy/interactions are 'imported' rather than the technical
info needed by the developers.

This is all macro-ised with a simple UI so I can 'check out', publish,
edit documents, create hyperlinks, or select sections of documents to
include.

Theres a few Word annoyances to overcome (particularly with relative
paths to other documents) and a bit of VBA behind it but nothing too
difficult.

Other things it does:
- hyperlinks change depending on whether the section is being viewed
as part of an individual spec or just included as part of a bigger
spec, so 'displays the _My Account_ page' is a hyperlink to another
Word document when viewed individually, or 'displays the _My Account_
page (see 3.4)' if it's part of a bigger doc and has to link to
another section in the same document.
- conditional text so text can be shown/hidden depending on whether
product features are turned on/off.

Stuart

Syndicate content Get the feed