Functional Specs (long and getting longer) [signed]

19 Mar 2006 - 10:31am
8 years ago
9 replies
508 reads
Bernie Monette
2005

Greetings!

There has always been a sense about web development that everything must be
new and other disciplines have nothing to add to what we are doing.
Particularly since web development has been done in a hurry. Remember that
old adage that Internet time was like dog years...

My view of the FS is that of a blueprint: you would never invest the
millions of dollars needed to build a bridge or a building without knowing
exactly what was required. Web development, interaction, digital, rich media
(whatever it is we do) design has to be done to the same or similar
standard. We have been lucky since most people don't know what it is we do
and if necessary we can bullshit them out of our office: but that is a
mistake.

The FS is the blueprint for everyone involved in the project: the wacky
marketing people, the odd IT folks, and the receptionist. Just like a
blueprint it explains what we what to do and what we have to do. It gives us
criteria to show the completed project as completed. It helps us control the
scope.

The particular scope that I worry most about comes not from the client,
which I can manage, but from programmers. It is the programmer working alone
who comes to a decision point and says "I think this works better so I am
going to add this feature" that scares me the most. So I want a good FS that
everyone understands there to guide that person and everyone else involved
in the project. There is a lot of creativity that goes into writing the
specification: there is no creativity (or very little) in following it.

In general parlance: a bad FS is better than none. So without a strong
standard what do we do? The best thing is to review and debrief projects
after they are done. In order to do that we need to document them well
beyond what we *want* to do. As well it can be difficult to find the time to
talk about old projects but without this process we don't have enough
information to improve the next project.

Cheers,

Bernie
--
Bernie Monette
InterActive Arts
Internet Presence Management
http://www.iaai.ca monette at iaai.ca 416 469 4337
>
> [Please voluntarily trim replies to include only relevant quoted material.]
>
> Interesting stuff. Jason Fried's rant-lette is thought-provoking. I think
> we've all experienced his frustration with the funk-speck as an appeasement
> document (which says more about the poverty of the team's process than a
> weakness of the document itself).
>
> That brings us to the focal issue of "audience". When viewing the
> Functional Spec, business stakeholders have one agenda, tecchies another.
> The biz guys are looking at business requirements and workflow, the tecchies
> are looking at data structures and code objects. A Functional Spec tries to
> provide the common ground for both worldviews:
> * It is a set of screen-based visual images + behaviors
> * that reflects the goals and tasks that have been described by the business
> side
> * as well as the constraints and requirements of the technical environment
> The trick is to create a document that someone actually wants to read.
>
>
> JF >So what do we do in place of a functional spec? We write a one page
> story about what the app should do.
>
> Jason's "one page story" is the accessible, descriptive overview that
> should accompany any well-conceived discussion. In my own writing, I append
> such an overview at the head of *every* document produced for the project:
> It is the context for all that follows.
>
> And we SHOULD push active design to the forefront: Most decision makers see
> the "vision thing" of what we're creating as a dance of screens, not as an
> abstracted Visio diagram (just watch their eyes glaze over). The sooner
> it's HTML, the better.
>
> But you gotta capture the total thought process on something, somewhere -
> You might want to call it a "functional specification". Note: I generally
> try to "annotate" my HTML prototypes with funcspec info, so that the model
> is itself a living document, but a good ole paper document has its
> advantages.
>
> Observation
> You know the story: They've already produced 50,000 lines of code - and now
> they call in an IxD person to "make it usable". Often one of the first
> things I do is to capture "what it is" in a Functional Spec (which never got
> written in the first place). It's scary how many software products move
> forward without capturing the basics...
>

--
------------------------ [ SECURITY NOTICE ] ------------------------
To: discuss at lists.interactiondesigners.com.
For your security, monette at iaai.ca
digitally signed this message on 19 March 2006 at 15:31:40 UTC.
Verify this digital signature at http://www.ciphire.com/verify.
------------------- [ CIPHIRE DIGITAL SIGNATURE ] -------------------
Q2lwaGlyZSBTaWcuAVdkaXNjdXNzQGxpc3RzLmludGVyYWN0aW9uZGVzaWduZXJzLmNvb
QBtb25ldHRlQGlhYWkuY2EAZW1haWwgYm9keQAKDgAAfAB8AAAAAQAAAFx5HUQKDgAAyw
EAAgACAAIAIH3hiLp0P+x4bt335e6TzbybTfBHwJm/OmHk8zUQFnIMAQA+EtF4nuL0AAm
7ySkqXgs8CNmd2t+EjVxbIsF1bUyE50MwMXFVB6p7xqBvYx0LZdxFn/fP7kHUgdSDYoCZ
X6c6U2lnRW5k
--------------------- [ END DIGITAL SIGNATURE ] ---------------------

Comments

19 Mar 2006 - 5:06pm
Andrew Otwell
2004

On Mar 19, 2006, at 2:17 PM, Bernie Monette wrote:

> you would never invest the
> millions of dollars needed to build a bridge or a building without
> knowing
> exactly what was required. Web development, interaction, digital,
> rich media
> (whatever it is we do) design has to be done to the same or similar
> standard.

Why? 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. Blueprints in those cases are required
by law and safety considerations.

I'd argue the exact opposite: because web sites and digital media is
merely bytes and pixels, there's no reason not to expect to
constantly change and renovate it, even as it's being used.

> It is the programmer working alone
> who comes to a decision point and says "I think this works better
> so I am
> going to add this feature" that scares me the most.

Yeah, that's annoying, but it's not really "scary", is it? 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.

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. 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.

19 Mar 2006 - 5:23pm
Robert Hoekman, Jr.
2005

> you would never invest the
> millions of dollars needed to build a bridge or a building without
> knowing
> exactly what was required. Web development, interaction, digital,
> rich media
> (whatever it is we do) design has to be done to the same or similar
> standard.

I would have agreed with this statement at one time, but I've come to
realize something. It's the web. No one has ever been killed by a
badly-designed web site. Inuries are rare.

A bridge does not have the option of failing. The web does. A web app
can be evolved, overhauled, redesigned, and refactored 1000 times in a
year.

-r-

19 Mar 2006 - 5:30pm
Taneem Talukdar
2005

[Bernie] "It is the programmer working alone who comes to a decision point
and says "I think this works better so I am going to add this feature" that
scares me the most. So I want a good FS that everyone understands there to
guide that person and everyone else involved in the project."

[Andrew] "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."

I don't think Bernie is suggesting stifling programmer's creativity. I think
the issue here is how much flexibility you have *after* the specifications
requirements document is completed.

Once the specifications are made, then developers are required to follow it
faithfully. Creativity is key in developing the document initially, and the
programmer's input comes into it during project negotiation between product
management and development.

Designers / Product managers certainly make changes to specifications - but
these follow a set process (in terms of formal change requests, with the
associated analysis).

[Andrew] "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."

I would be very careful with that generalization. Ad hoc decisions that
result in a difference between the implementation and what was asked for in
the specifications document will often cause serious headaches. The more
complex your project gets, the smaller the change required to cause havoc.

I have worked with a system that had on a high level, 6-7 major technology
pieces, and catered to over a million users worldwide. We had a ridiculously
trivial implementation deviation that resulted in impact to everything from
documentation to subsequent product updates.

For a fairly simple website, sure, such a detail probably won't be a big
deal. But why not do it right from the start? The requirements document
with sign-off from product management, development, and anyone else relevant
is the *gold* standard. No-one should make changes after this point (or else
use a change request process and get sign-off on the changes).

Just some thoughts :)

-Taneem

On 3/19/06, Andrew Otwell <andrew at heyotwell.com> wrote:
>
> [Please voluntarily trim replies to include only relevant quoted
> material.]
>
>
> On Mar 19, 2006, at 2:17 PM, Bernie Monette wrote:
>
> > you would never invest the
> > millions of dollars needed to build a bridge or a building without
> > knowing
> > exactly what was required. Web development, interaction, digital,
> > rich media
> > (whatever it is we do) design has to be done to the same or similar
> > standard.
>
> Why? 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. Blueprints in those cases are required
> by law and safety considerations.
>
> I'd argue the exact opposite: because web sites and digital media is
> merely bytes and pixels, there's no reason not to expect to
> constantly change and renovate it, even as it's being used.
>
> > It is the programmer working alone
> > who comes to a decision point and says "I think this works better
> > so I am
> > going to add this feature" that scares me the most.
>
> Yeah, that's annoying, but it's not really "scary", is it? 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.
>
> 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. 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.
>
> ________________________________________________________________
> 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
>

19 Mar 2006 - 5:33pm
Chris Ryan
2004

On 19-Mar-06, at 2:23 PM, Robert Hoekman, Jr. wrote:

> I would have agreed with this statement at one time, but I've come to
> realize something. It's the web. No one has ever been killed by a
> badly-designed web site. Inuries are rare.

Physical injuries perhaps; but legal or financial injuries, perhaps not.

> A bridge does not have the option of failing. The web does. A web app
> can be evolved, overhauled, redesigned, and refactored 1000 times in a
> year.

The user interface, maybe. The whole software system underpinning a
large functional site, no.

Chris

20 Mar 2006 - 1:28am
Oleh Kovalchuke
2006

First on consequences: If ecommerce website were to fail me by $20 I
might not be killed, but their business would suffer by more than $20.
If Alta Vista were to consistently fail me by a more arcane option
instead of what I am looking for their business would suffer (as
indeed it did). To illustrate this further recite this sentence to a
web business owner as you deliver malfunctioning web site to him:
"It's the web. No one has ever been killed by a badly-designed web
site."

On causes: The ease of changes to web _application_ is a myth, which
does not take into account the holistic nature of system development -
as you change something here, you need to keep in mind as well as
retest eleven things over there, because safety as well as usability
are emergent properties of system design. In my experience changes in
web application are not easy at all.

I have just finished reading "Safeware" by Nancy Leveson, it gives
nice overview of these topics. Funny too.
--
Oleh Kovalchuke

"And they looked upon the software, and saw that it was good. But they
just had to add this one other feature..." G.F.McCormick - Epigraph
from Safeware.

On 3/19/06, Robert Hoekman, Jr. <mmbeta at gmail.com> wrote:
> [Please voluntarily trim replies to include only relevant quoted material.]
>
> > you would never invest the
> > millions of dollars needed to build a bridge or a building without
> > knowing
> > exactly what was required. Web development, interaction, digital,
> > rich media
> > (whatever it is we do) design has to be done to the same or similar
> > standard.
>
> I would have agreed with this statement at one time, but I've come to
> realize something. It's the web. No one has ever been killed by a
> badly-designed web site. Inuries are rare.
>
> A bridge does not have the option of failing. The web does. A web app
> can be evolved, overhauled, redesigned, and refactored 1000 times in a
> year.
>
> -r-

20 Mar 2006 - 11:28am
Robert Hoekman, Jr.
2005

OK, I'll come clean now. My statement was really just about playing devil's
advocate. Honestly, I'm sort of "on the fence" when it comes to the "plan
vs. build" debate. Part of me thinks Cooper et al has it right, part of me
thinks 37signals has attained a Nirvana with their Getting Real approach.
These are the two sides for me. One says "Plan, plan, plan". The other says
"Just build it".

I disagree with enough things on both sides that I'm finding myself just
trying to invent my own path.

Sorry to throw out such a baited statement (the one about it being easy to
iterate on the web), I just needed to get some other perspectives. I agree
that it's often very difficult to iterate web apps, because, as Cooper
points out, you have to convince programmers that something is worth
changing and that's no small task. But I have a programming background, and
I'm less afraid to iterate than some might be. I also am pretty successful
in getting programmers to do what I want them to do (probably because I know
them so well, being a reformed programmer myself). So I don't entirely agree
that plan, plan, plan is the way to go either. It takes a lot of time - that
I simply don't have - to do such thorough user research and write personas
and scenarios. I disagree that software design should take place entirely
away from the computer (Cooper), but I also disagree that you should go
straight from sketh to code (37signals).

My job gets done by whipping up wireframes at light speed, reviewing what
gets built, etc. I don't prototype to design, I prototype to simulate
interactions and functionality I can't clearly explain on paper. I don't use
the same tools to prototype as the ones that will eventually be used for the
final release, so my prototype code doesn't live on in releases.

-r-

On 3/19/06, Oleh Kovalchuke <tangospring at gmail.com> wrote:

> On causes: The ease of changes to web _application_ is a myth, which
> does not take into account the holistic nature of system development -
> as you change something here, you need to keep in mind as well as
> retest eleven things over there, because safety as well as usability
> are emergent properties of system design. In my experience changes in
> web application are not easy at all.
>

20 Mar 2006 - 1:50pm
Robert Hoekman, Jr.
2005

> Yes! This can be regarded more as functional specs than as a
> prototype, isn't it?
> It's just theh you choose to express yourself in Visio instead of Word.
>

Well, I prefer Axure over Visio any day of the week, but yes, prototyping is
not about design for me, it's about simulation. In fact, they should be
called "simulations".

In that sense, Cooper is right - prototypes, in their traditional sense, are
manufacturing proof. What I'm creating are simulations. Totally different.

Hmm.

-r-

20 Mar 2006 - 3:50pm
Ari
2006

Axure is ok. It depends on your environment and how you work. I rarely have
the time to spend developing a simulation so Visio works much better when it
comes down to the nitty gritty of developing quick and dirty specs.

On 3/20/06, Robert Hoekman, Jr. <mmbeta at gmail.com> wrote:
>
> [Please voluntarily trim replies to include only relevant quoted
> material.]
>
> > Yes! This can be regarded more as functional specs than as a
> > prototype, isn't it?
> > It's just theh you choose to express yourself in Visio instead of Word.
> >
>
>
> Well, I prefer Axure over Visio any day of the week, but yes, prototyping
> is
> not about design for me, it's about simulation. In fact, they should be
> called "simulations".
>
> In that sense, Cooper is right - prototypes, in their traditional sense,
> are
> manufacturing proof. What I'm creating are simulations. Totally different.
>
> Hmm.
>
> -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
>

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

22 Mar 2006 - 9:39am
Bernie Monette
2005

Of course this is the problem I referred to: if I am paying the programmers
to do the work then I want them to follow the functional specification. At
the same time I also want them to speak up when the FS is being written. I
also want them to speak up at meetings: this goes for everyone.

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.

Part of the problem is that we tend to use a cascading model of project
management. That is we gather all the information about what we think the
project is about and then, release the hounds (mixed metaphor-sorry), or
pull the trigger. Then you learn that there are inherent problems in the
design so how do we incorporate what we learn about the project and still
remain profitable? Bullets don't like to go around corners and the same is
true for projects.

Iterative project management shows some promise: choose the most important
thing in the project and develop and test, develop and test. Writing a
proposal and estimate for this kind of method is not easy.

Cheers,

Bernie

Ps
Al: I love your tutorial.

--
Bernie Monette
InterActive Arts
Internet Presence Management
http://www.iaai.ca monette at iaai.ca 416 469 4337

>
> 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-

>

--
------------------------ [ SECURITY NOTICE ] ------------------------
To: al at mojofat.com, mmbeta at gmail.com,
discuss at lists.interactiondesigners.com.
For your security, monette at iaai.ca
digitally signed this message on 22 March 2006 at 14:40:18 UTC.
Verify this digital signature at http://www.ciphire.com/verify.
------------------- [ CIPHIRE DIGITAL SIGNATURE ] -------------------
Q2lwaGlyZSBTaWcuAVdhbEBtb2pvZmF0LmNvbSwgbW1iZXRhQGdtYWlsLmNvbSwgZGlzY
3Vzc0BsaXN0cy5pbnRlcmFjdGlvbmRlc2lnbmVycy5jb20AbW9uZXR0ZUBpYWFpLmNhAG
VtYWlsIGJvZHkAXQgAAHwAfAAAAAEAAADSYSFEXQgAAHoCAAIAAgACACB94Yi6dD/seG7
d9+Xuk828m03wR8CZvzph5PM1EBZyDAEAPhLReJ7i9AAJu8kpKl4LPAjZndrfhI1cWyLB
dW1MhOeZpzOIPNprSZC7mAe/JmfKGJbsPKRm5qFDj/hZl/TpDepUU2lnRW5k
--------------------- [ END DIGITAL SIGNATURE ] ---------------------

Syndicate content Get the feed