09 Feb 2005 | Rob H said...

Jason,

I couldn't agree more with you on Functional specs are often appeasement documents. Theyre about making people feel involved.

I also think that these type of documents are CYA and pass the buck when the sh*t hits the fan when things don't work out.

I would love to try this approach out on a side project I will start working on..The approach you descibe would be very difficult to implement in a enterprise setting. What you describe goes against the grain of software development (not to say that its the best or right approach).

I can't wait to read more about the process.

-R

09 Feb 2005 | sloan said...

That is ALWAYS the problem, we don't engage our clients in the solutions and use documents to "prove" that we did our job. The problem can be summed up as that we are presenting stuff to them, not getting them to create stuff. Or be involved. In past jobs where I was able to work WITH the clients on solutions there were never any problems because they helped create the solution. So that meant 1) they already had buy in to the ideas, we didn't need to convince them and 2) we all had the same understanding because we were in constant communication. It requires a lot FROM the client, but in the end, is waaaay more cost effective and rewarding. Oh, and the extra education that the client got about design just made us look even better!

09 Feb 2005 | Anthony Baker said...

Man, this is great. Absolutely agree.

On every project I've done, no matter what kind of documentation that has been written, most clients _really_ don't start offering viable feedback until they see an interface in front of them. For them, this is the point where they go "oh, this is what we've been talking about -- okay..." and ideas really start to flow.

Hell, more often than not, they start thinking of items they'd like to see and things they'd like to be able to do that they hadn't even considered before.

Had a recent client who'd been working with a company to develop an application and they hadn't done ANY serious front-end design. They'd been working on the project for months and I came on board, hired by the client to "make it look nice."

I started to do UI design -- first in Illustrator and Fireworks -- and quickly started to see all kinds of breakdowns in terms of how the application was actually designed, how things wouldn't work -- or would be outright missing -- that the user/customer would need. Anyhow, a small "make it nice" project ended up becoming a very big project, thankfully.

I only wish I'd come in at the beginning -- they could have saved a lot of time and money.

The interface is the application, folks.

09 Feb 2005 | Garrett said...

This is essentially the process we've come around to naturally. While we spend our time in Visio instead of going straight to HTML, we are starting to bypass Use Cases and other related documents in favor of using very detailed wireframes as the requirements.

It was uncomfortable at first, however, now I'm starting to think we should have done this a long time ago.

The one page story is a very interesting twist, but it seems like it could be very very subjective as to what needs to be specified and what doesn't need to be specified. Shorten or lengthen as necessary? It just feels so vague.

09 Feb 2005 | AK said...

So how much is a one page story worth? If someone important in the company came and asked, why are we spending $XXX on your project, would this story justify the cost?

The value of having these documents as "apppeasement documents" is important. You have to play the political game and with functional specs everyone knows how to play the game.

If I'm working with a small client I can use the one-page story. If it's someone trying to justify their budget they will not get the money.

09 Feb 2005 | Chris S said...

That's very well put! It addresses stuff I'm dealing with right this minute, too.

Once my job turned into web app development more than simple web design ( I work for a large local organization ), I drew up all my documents and built my prototypes and, after the initial honeymoon of "it's so great we have someone who can do that," began to meet growing resistance from the staff who would be using them.

Not all of them were whiners, either (hehe)...they had very good points.

Only smart thing I did was chunk my plans and talked to them, picked up a pencil and paper and drew pics of interfaces, etc. They told me what they needed to be able to do and how (in non-geek speak, of course), and I went back to my desk and translated their requests into php, mysql, html, css, and javascript.

Everybody ended up being happy. My turnaround time is shortened so stuff gets out quicker OR I can spend a little more time on nifty features/requests. They're happy cause they get what they need and it works like they need it to...and they spend more time talking about what a wizard I am than what a big pain in the ass dictator I am.

And because of all that, if there are potential problems with what they want (for any number of reasons), they're more likely to work with me to find alternate solutions.

09 Feb 2005 | ramanan said...

How would you apply this approach to designing and implementing an HTTP server? Or a Ethernet Card Device Driver? A lot of software gets written that doesn't have widgets for users to click on.

09 Feb 2005 | JF said...

How would you apply this approach to designing and implementing an HTTP server? Or a Ethernet Card Device Driver? A lot of software gets written that doesn't have widgets for users to click on.

I wouldn't. This process wouldn't make sense in that context. I'm talking about things with interfaces. Web-based apps, software apps, etc. Things that have a front end.

09 Feb 2005 | Don Schenck said...

Isn't the "story" just a high-level Use Case, or a Use Case Summary document? What's the diff?

09 Feb 2005 | steeltoes said...

OK I'll bite. I hate writing functional specs specifically because I am really just throwing together a bunch of thoughts. I'm not really creating anything new, just creating a strawman for everyone to "agree" to. We spend hours hashing it out, and then ignoring it all.

Too many times have my functional specs been trashed after "agreement".

At the meeting where I presented the first draft of the functional spec. what did everyone do? You guessed it, looked for the wireframes and sitemaps. It got to a point I just started with wireframes that contained notes and built the functional spec after these were agreed on.

However, I think that functional specs do some very good things that aren't covered in a simple one page story. They give the developers a look at what happens "if". It tells the developers where the client is expecting data to be captured to. It informs the developer as to the environments and parameters that must be maintained. If we skip the functional spec and only focus on the experience where do the technical parameters get captured?

Anxious for a reply.

09 Feb 2005 | ramanan said...

I know you wouldn't, but your post kind of glosses over the fact that people write all sorts of software. In many cases all you can do is write out what your program is required to do.

That said, I do think this is a good way to design certain kinds of programs. Many times clients can't articulate what they want clearly, but they can probably tell you if your mock-up doesn't match what they had in mind.

09 Feb 2005 | JF said...

If we skip the functional spec and only focus on the experience where do the technical parameters get captured?

The details come out in the visual design (which becomes "the spec"). The design is where the experience happens. It's when you really figure out what this product is going to do, what data is going to need to be displayed when and where.

We'll talking more about this in a future article.

09 Feb 2005 | Rob Sutherland said...

We write a one page story about what the app should do.

Isn't this one page document then the spec document? Written clearly and in understandable language. Talk about the what not the how.

We work similarly, but we consider the description document to be a specifications document. That document typically has sketches and/or wireframes that help describe the application. Then we refine the design and built it and the backend.

(semantics, I know)

09 Feb 2005 | JF said...

Isn't this one page document then the spec document? Written clearly and in understandable language. Talk about the what not the how.

The story is the big idea. There's no talk about specifics. No talk about granular features. No talk about screens or pages or detail function. It's basically the big idea, the personality, the vision.

The interface design is the "spec." Everything comes from the interface design. We build from the customer's point of view. The customer is at the middle of everything. To the customer, the experience, the interface is the product. We agree and that's why we start there. We start from the customer experience instead of grafting it on later.

To be continued.

09 Feb 2005 | Eric Goldberg said...

Quite insightful. The few times I am forced to write a functional spec, I find myself thinking about what I would want to see and click, as a user. Sometimes a specification is helpful for other applications, but not often for describing desired functionality.

09 Feb 2005 | bob said...

No question the interface is important (for the type of software being posted about - versus stuff that doesn't really have a web-based/clickable type interface), but I'm not sure I totally agree with the idea of scrapping functional specifications. Depends, I suppose on what you're -putting- in the functional specification.

As far as I can tell, you could easily put interfaces into the functional specification - wire frame mockups, quick "look 'n feel" templates.

Just because you have an interface with a button that says, "Reports", doesn't mean anyone has a clue what clicking that button will do. Unless you're building *every* single interface out, but I'm not sure you'd know how to do that without the details of a functional specification.

I would integrate interface prep work and a functional specification together - do them simultaneously so that you can start to provide the client with a picture and words that describe the picture.

Interfaces also don't address all the needs of developers. In actual fact, developers typically don't even care about the interface - the back-end and front-end are separated - the back-end should be built independently of the back-end. Otherwise you're pigeonholing the system to be inflexible (designed to the specific front-end only, with no thought to evolution of the system from there). A functional specification to me doesn't just address the high level functionality of a system but also addresses development requirements (needs to be fast, secure, scalable - pick 2 of 3, etc.), and also starts to shape how developers are going to build things. A pretty picture mockup doesn't give them enough information.

09 Feb 2005 | David Heinemeier Hansson said...

Developers who "don't care about the interface" are harmful creatures to have on a project team that works with a "The interface is the product" kind of software. Make them care or get them off the team.

Equally harmful is the notion that you should attempt to gather all information before getting started. Designing the interface first purposely leaves out much information in order to force conversation during the build phase. The only phase where you're in a position to ask the best questions.

And yes, you most certainly do need to design all the screens. Not doing so leaves the most important part of product subject to whatever the programmer feels like doing when he gets around to working on it. He'll be wearing his programmer hat and do a terrible job at designing the interface.

The funny thing is that having "complete" screens before starting an iteration (remember that you don't design the whole app before writing a line of code) makes it so much easier to be a programmer. The design can often be read off the interface and you avoid another of the great pitfalls of programming: "designed to the specific front-end only, with no thought to evolution of the system from there"

eXtreme Programming have a few good sayings about that: Do The Simplest Thing That Could Possibly Work and You're Not Gonna Need It. Trying to guess what the evolution of the system is going to bring is inefficient at best and utterly destructive at worst.

Carrying around baggage of fortune tales of one possible future is going to harm your ability to deal with the present. Worry about today today and leave tomorrow's troubles for tomorrow.

You might want to read up on agile software development in case this seem ludicrous. I can recommend Kent Beck, Martin Fowler, and Alistair Cockburn as a few starting points.

09 Feb 2005 | andrew said...

It's hard to avoid the temptation of a "functional spec" with all of its reassuring "It is a requirement that the software shall..." lines. But they are terribly useless things. I've never met anyone who isn't better at simply looking at a screen and saying, "hmm, that's not what I want. Let me show you something else."

Also had to comment on this comment above: "Just because you have an interface with a button that says, "Reports", doesn't mean anyone has a clue what clicking that button will do."

It's funny, bob, that you chose "Reports" as your example. In every application I've worked on that contains reports, they were *always* one of the hardest parts to design. Almost everyone will just go: "Oh, you know, REPORTS. Just pick some data points and we'll be fine."

It's much harder for people to really think about reporting and figure out what's needed than you'd think. They are also often one of the app's dumping grounds: "just add a new report, after all, it's just listing data we already have. Someone's bound to want it someday." Don't get me started on Reports.

09 Feb 2005 | Oliver Schwarz said...

Huh? Your ideas sound great to me, but a few questions keep sticking in my head. In my current state of experience, I think that functional specs in mid-sized web-projects (10-100 mandays) are inevitable. I believe, the crack between customers' expectations and your interpretation is even wider - even with rapid prototyping. The other thing is, that I've learned, that a lot of the customers can not distinguish between prototypes and productive releases. Furthermore, they keep changing vital initial requirements as soon as the first prototypes arrives.

IMHO the conclusion of your article is to have a proper change management as the project flows. It's not about writing func specs or not, it's about dealing with so-called moving targets. I agree, that targets can not be specified in one big effort at the start of a project. That's why we often use wikis for visionary docs/func specs and keep communication alive and open.

I found it hard to calculate efforts for projects (especially marketing-driven ones) based on loose specs. Maybe it's a german phenomenon, but - you know - without calculation up to the very minute, you get nothing approved here ;) As much as I would like to start with loose specs and narrow them as the project goes on, as much the customer dislikes not knowing, what the project costs in the end. Am I wrong?

09 Feb 2005 | Mike P. said...

"Everyone is reading the same thing, but theyre often thinking something different."

So true. I inadvertently did the story thing on a project not too long ago (due to a major rush) and it work out great. You start describing to them what it will do: "you'll have these options, click here, do this" and they get it, and we get it.

I've heard back thru third parties that the client is quite happy with their product. Funny because I keep waiting for a "we needed it to do this, not that!".

09 Feb 2005 | David Heinemeier Hansson said...

Oliver, the solution to not knowing what something is going to cost is deciding what it WILL cost. Discuss the general vision for the project with your client. Decide on the major objectives you want to address. Then say: "We're going to built the best system we can under the vision with X amount of dollars".

The system is done when you run out of dollars. Or possibly before that if the customer is happy half way through. Or possibly later than that if he likes the stuff he's getting so much that he wants more.

10 Feb 2005 | Geof Harries said...

We're all giving this "story" idea so much praise, but in reality it already has a name: BRD, short for Business Requiremetns Document. "Story" is just a little cuter and less threatening by the sheer virtue of its name.

FRDs come after you investigate, discuss and document real working people's requirements and restrictions. BRDs look at the bigger, and smaller, picture in close detail. BRDs truly bring the human side of software and app development to the forefront - laying the path for every other technical aspect down the road.

They could be 1 page (I wish), as above, or they may be 100 pages, but they're still BRDs.

geof

10 Feb 2005 | One of several Steves said...

I'm highly suspicious of absolutist statements when it comes to software design and development. Always write a functional spec. Never write a functional spec. Both are equally dogmatic and equally full of pitfalls.

A "story" is never going to give developers enough to go on if you're building a web-based app that has to interface with a multitude of exterior systems, legacy databases, etc. Interface design isn't going to help them much, either. Good database diagrams would. Good technical requirements document would. But the "story" and the wireframes and comps aren't going to help them much. And, like it or not, sometimes we do have to make the interface accomodate what's going on in the backend, or else spend a ridiculous amount of money to get legacy technology to behave the ideal way, instead of a reasonable amount of money to get it behave in an acceptable way.

The key takeway is to have the right criteria drive the design and development, and use whatever tools needed to best communicate that. Call them whatever works (as Geoff correctly points out, a BRD by any other name still smells as sweet).

Flexibility and using the available tools to get the job done effectively is paramount. Dogmatic approaches get in the way. "Don't write a functional specifications document" is frankly just as stupid as "Always write a functional spec." Sometimes it makes sense not to; sometimes it doesn't. Dogmatic rules don't encourage that kind of flexibility.

10 Feb 2005 | JF said...

Come on... Of course everything depends. Everyone knows that.

I'm writing about our process. This is how we do it on our projects. It doesn't mean it will work for everyone or in every case, I'm just sharing how we do it.

10 Feb 2005 | David Heinemeier Hansson said...

We're saying that functional specs are bad project drivers. I don't consider the API specification for a remote or legacy system to be a functional spec. That's more a statement of fact. Given A, you'll see X. It's a description of existing behavior.

What we rail against is using functional specs as a determiner for future, unknown behavior. About making decisions before you have the feedback available to make good ones. About saying yes to get an illusion of agreement.

That's not at all the same as saying all written documents must be burned. That would be silly. It's saying that the role of the functional spec is inappropriate, grossly overused, and harmful for the majority of projects.

10 Feb 2005 | Jaime said...

I completely agree that you should work from the interface out (or in, depending on how you look at it). But, this is not a new idea. This is the basic premise of FLiP (Fusebox Lifecycle Process). It has been used by Fusebox developers (mostly Cold Fusion) for quite some time. It is geared completely towards working directly with the customer to build the exact interface that the application needs to have and then build the "back-end" to support the interface.

10 Feb 2005 | One of several Steves said...

What we rail against is using functional specs as a determiner for future, unknown behavior. About making decisions before you have the feedback available to make good ones. About saying yes to get an illusion of agreement.

That I can - and do - agree with. But I don't agree that that's something that's inherent in functional specs but not a problem with other forms of documentation. Any process that's so inflexible as to treat whatever was established in early days as if they were written in stone is doomed to have problems, whether that comes from a functional spec document or a wireframe. That's the issue. Not which piece of paperwork you use.

JF, I appreciate that you're describing your process, but when you go around the country conducting a seminar where you demonstrate "what it takes to launch a web-based application" and you use language as direct as "Don't write ..." it comes across as prescriptive, not descriptive of how you happened to do things.

10 Feb 2005 | JF said...

JF, I appreciate that you're describing your process, but when you go around the country conducting a seminar where you demonstrate "what it takes to launch a web-based application" and you use language as direct as "Don't write ..." it comes across as prescriptive, not descriptive of how you happened to do things.

The workshop we put on is called The Building of Basecamp and we talk about how we built Basecamp.

People come to hear us talk about what we did and our opinion of what to do based on our experience. Just like anyone with a point of view, we put ours forward and believe in what we say. And, yes, we are prescribing a way to work. We have ideas about this and are putting them out there.

But of course we know it depends and people understand that. I don't think I have to hedge every point I make with an "it depends disclaimer." It's always implied.

10 Feb 2005 | John Sands said...

Great post, especially the line 'To be continued...'.

If you happen to have one lying around, how about a real world example of a one page story?

10 Feb 2005 | brian b said...

this is a great "thread" since i am actually doing just that for 2 projects I'm working on. I hate writing out tech specs, and as a result am designing the whole thing in photoshop before i take it to html, then giving that to the programmers. I did this this way because i didn't have a firm tech spec in my mind though.

anyway now i really want to go to the next building of basecamp.

10 Feb 2005 | John Kopanas said...

I wrote a one page user story for an application I am looking at building and I found it ended up looking like an overall general user scenario. Should it sound like a user scenario or should it be more like a general description of the main features?

I find myself in my one page user story saying things like "the user will be able to either do x and y from here". Is that how it should be written?

Thanks for your feedback. It would be greatly appreciated.

10 Feb 2005 | JF said...

I find myself in my one page user story saying things like "the user will be able to either do x and y from here". Is that how it should be written?

No. The story isn't about specifics. It's big picture to set the tone. The interface defines the specifics. You don't have to describe what X and Y is, you just design X and Y and then everyone understands what X and Y is. Further, designing first lets you see if X and Y make sense at all -- something that is very difficult in an abstract written document.

10 Feb 2005 | Brian said...

So, to clarify, you tell your clients "We will work for an undetermined number of hours at our standard rate until we have developed a finished specification for your application"?

If that works for you, you have clearly leveraged your reputation well, because that is not how 99.9% of businesses allocate funding. Without some list of features or information, how do you even know what you'll be designing? Especially in the case of complex business applications, the interface is often the tip of the iceberg. How do you document those features/behaviors?

Although the FRD is not the end-all, be-all document, I consider it a step of the iterative process. We first talk broadly about a system, we then generate a business requirements document, then create an FRD with more detail, and then begin creating wireframes that detail the functional requirements even further and so on. We continue interating until the system is finished (or runs out of money). The idea is to move, in steps, from the abstract to the finished product.

Your relationship with your client must be an ongoing series of agreements. The FRD should not be the first and last, nor should the interface. Fixed cost engagements may be slightly different, but the intent remains the same.

10 Feb 2005 | David Heinemeier Hansson said...

Economic constraints are great. So rather, the wording would be "we'll work to give you the best application we can within the specified vision/overview and X amount of dollars." Fixed time, scope, and price is not a viable approach to software development for the vast majority of projects.

Since the business usually do require time and price to be fixed, that leaves you with scope as the lever. And since you're working by delivering the highest business value first, that approach ensures that you get the most value for your development dollars at the earliest time possible.

Without being forced to make a world of bad decisions up front in a functional specification.

But sure, it does require trust. That trust is built by delivering working software early and often. And of course, by working with clients that understand that fixing scope, price, and time is not only impossible, but harmful.

10 Feb 2005 | Mason Houtz said...

Sorry man, but I honestly think you've completely missed the point. The problems you describe in your article here can be attributed directly to lazy communication skills (on both ends) during the process of the spec-writing.

You just said the spec document was the problem, then turned around and wrote a different kind of spec document.

The problem you're really trying to tackle is the lack of critical thinking skills on the part of the client. And you can't tackle that problem with a 1-page story or any spec document. That doesn't mean the doc doesn't have value. And it doesn't mean it shouldn't be written.

Another way to tackle this real phenomenon you've described is to go ahead and write whatever form of spec document you prefer. (Your 1-page story is as good a method as those retarded sheets of bullet points.) I don't care what your method of description is, so long as it is complete and clear. That's supposed to be your big thing right?

THEN, what you have to do is drag proof of understanding out of your client the same way a teacher drags answers out of a brain dead trig class. You sit there and ask them questions.

Basically, you have to do their thinking for them. Make them explain back to you exactly how pages are going to work. Hell, grade them. If they flunk, send them home with the homework and test them again tomorrow. Put it on tape if you need documentation. The fact is, clients lack critical thinking skills because they're largely a bunch of lazy cubical inhabitants with logical processes that were honed by years of watching Cheers re-runs.

It's not always the client's fault either. Developers are often remarkably crappy at putting their thoughts down on paper. One way or another, the real solution is ultimately education reform because you've just described a problem that results from dumb humans grunting noises at each other.

10 Feb 2005 | David Heinemeier Hansson said...

The fact is, clients lack critical thinking skills because they're largely a bunch of lazy cubical inhabitants with logical processes that were honed by years of watching Cheers re-runs.

You're right, Mason. Getting Real is not an appropriate approach for your needs. The process we're laying out is completely incompatible with a world view like that.

10 Feb 2005 | Mason Houtz said...

Then we're in agreement. Have a nice day in whatever reality you think "Getting Real" applies to.

10 Feb 2005 | Greg said...

We do something quite similiar when we are developing web apps.

In fact, what Jason is describing looks like a variation of FLiP (Fusebox Lifecycle Process) which takes you from gathering requirments to full prototype, using personas, wireframes and prototypes. (wireframes mean something different in FLiP terms, it is a skeletal version of teh web app, a page by page representation of the final app with only text descriptions, in essence determining what the app will do where) We also use flowcharts and traditional wireframe page layouts to communicate visually to the client. You can get a really good price quote of that much (minus the prototype of course)

Anyways if you are interested in looking at FLiP check out fusebox.org

10 Feb 2005 | Elling Bjstad said...

I think you'll have to draw a line between projects that involve a lot of new invention and projects that don't involve that much invention.

If a project involves invention, I think it'll benefit from being done as an iterative process, and in such cases I think it's good to just write down a small description of the problem domain and the solution that you envision, and then to gradually refine the specification through gradual steps of prototyping.

But if you're doing something that's of a more repitive nature, then I think it's possible to pin it down more accurately at the outset of the project. Say, if you're a bridge engineer, and you've built a hundred bridges before, then you'll benefit from planning it out in detail BEFORE you start working on a new bridge. Why? Because you have enough control of the different parameters to be able to write a detailed specification. And then you probably should do it, I think.

So, I probably agree with you: If you're on a project where there are a lot of unknowns, you shouldn't fall in the trap of pretending that you know the answers to the unknowns. That'll be very much like fooling yourself (and others).

To finish my argument, I'd like to cite chief poet of the White House, Donald H. Rumsfeld:

As we know,
There are known knowns.
There are things we know we know.

We also know
There are known unknowns. That is to say
We know there are some things
We do not know.

But there are also unknown unknowns,
The ones we dont know
We dont know.

10 Feb 2005 | Cody Briggs said...

I have mixed feelings and think that functional specs have both positive and negative qualities, but throwing them out altogether seems completely unrealistic in the agency environment where I work.

All new business starts with a proposal or scope of work document. This document is much like your one page story concept - I suppose. It doesn't establish granular functional reqs (e.g. validation on the email address field is required - both formatting and for completion). These are the types of details that functional specs cover.

Some really important issues that the proposed one page story solution don't address, in my mind, follow:

1. What happens when you need to outsource a project - is the one page story enough to hand-off to an external project team?

2. How does the QA team go about testing the application? What do they have to test from?

3. Sure, effective client communcation and participation can solve late-in-the-game scope creep and budget melt-down, but this practically never happens. Whose fault is that? Clients are busy and we are busy, it's just the way things are.

Our specs are developed in tandem with detailed wireframes by an interaction designer - which works perfectly for us. Wireframes give the visual people an idea of how the application will function, and can be made interactive using navigation elements in Acrobat.

10 Feb 2005 | Jason Hummel said...

I'd be interested in how you guys (37 signals) sells this process to external clients, not just for internal projects. When a client is expecting a set amount of functionality. How do you tell them you want to pare it down by 2/3 to make it fit on one page and add in the missing functionality after launch? How do they take that suggestion?

10 Feb 2005 | JF said...

When a client is expecting a set amount of functionality. How do you tell them you want to pare it down by 2/3 to make it fit on one page and add in the missing functionality after launch? How do they take that suggestion?

Like David said ("Fixed time, scope, and price is not a viable approach to software development for the vast majority of projects"), a fixed price, fixed scope, in a fixed time frame isn't realistic. Something has to give. It's the same as saying you want something cheap, fast, and good. Pick two, but you can't have all three.

For example, if time is fixed, it's usually scope that has to give. If you need to launch by March 1, well then you can't be guaranteed that everything you want will make it into the first release of the product. We explain this up front to our customers.

If a fixed price, fixed scope, and fixed time frame is only thing that they will accept, well then perhaps we're not the right team for them. If someone else wants to make the "pick all three" promise that's fine, but we won't make a promise we know can't be kept.

10 Feb 2005 | Allan White said...

Wow, there's a lot of commentary here - some very good and insightful ideas here. One question: in your mind(s), how does the "story" vary from a well-written use case? A singular story seems like it would work for a singular type of user with a singular goal or need. I don't see how to cover all the bases without at least having several "characters" in the story (i.e. personas).

Overall, I really like the idea of napkin sketches early on in the process. It's much more relaxed (no high-falutin' tools), and less intimidating (everyone understands pen & paper). I'd certainly be happy if I never had to read or write a functional spec again.

10 Feb 2005 | JF said...

Another thing I'll add...

Working with the right clients is absolutely critical. The trick is knowing when to say no. The wrong client can kill morale, force good employees out, and cost you big opportunities. Working the right client isn't work at all -- it's a pleasure.

11 Feb 2005 | marchLAST said...

09 Feb 2005 | bob said...
...but I'm not sure you'd know how to do that without the details of a functional specification.

Heh, bob, that's the whole point. We (and I'm considering myself a like-minded person to JF, I do not represent 37S) do know how to build out the details without the functional spec. I can't tell you how many times, when it finally came time for the front-end to be built, I would have to insert all of the corrections that the "technologists" and the client had left out while agreeing to their glorious functional spec.

JF, I think what you're proposing is for a certain group of people only. Many of the projects at a FORMER employer of mine, didn't have the benefit of knowledgable client-side developer and they just built what they were told. Problems (that would seem glaring to you and me) didn't get picked up until the weeks before soft launch when QA was going on.

Process is nothing without the right people, and the right people can adapt to any process. I haven't met a catchy named n-phase process that I didn't hate, I was even responsible for creating a few of them in a past life.

11 Feb 2005 | Craig said...

Reminds me of a software engineering class I took once. Spent the whole quarter developing reams of pretty useless documents for the "spec". Lots of data-flow-diagrams that meant nothing, pages and pages of db schemas that didn't get used, and more pages of garbage I don't even remember. They had to be in there because that's the way its done.

Of course the project was a GUI tool for scheduling - heavy on the UI bits, light on the data. The instructor came from an enterprise background designing large data intensive systems and we spent the entire quarter trying to come up with data driven design specs for a GUI driven application. It didn't work or even get off the ground. Starting with the UI would have been the best way to go. I did do a bunch of UI design that did bring up a lot more questions and problems to solve than any of the other work did - I just wish we could have started with that from the beginning because then wwe might have made some sort of progress.

11 Feb 2005 | Arne Gleason said...

While Jason does present in a prescriptive way, its probably why it has provoked so much good consideration and commentary. I have two points that I dont think parrot the above comments too directly (at least I can pretend to be adding something to the discussion):

1. Words are a commodity. Value is ascribed as much or more to quantity than to quality (500 pages of text --- this is great!). Id say its a factor that impossible to avoid (as much as I wish otherwise, as Im a very slow writer).

2. I wouldnt abandon or even lessen current dependency on functional specs. I do agree with all the problems raised by Jason, and I do think the process that drives them is most often broken. But, I think you can have it all, including functional specs.

11 Feb 2005 | Doug Lindauer said...

Something that's almost universally omitted from these kinds of discussions is a recognition that a database-centric app is a very different animal than a device driver program, or a scientific analysis program, etc. etc. All the same kinds of things go on in each type of project but the emphasis has to be on different areas.

For example, on a database-centric app, if you don't have a good structure, all the pretty front ends in the world won't keep the database from eventually becoming crap. So there darn well better be a major emphasis on creating a good database model up front. If you're creating an important scheduling program that has very simple database requirements, then you better focus on the specifics of the front end and perhaps an FRD. Craig made a really good point about this in his post above.

Personally speaking, I've developed 15 - 20 database-centric apps from the ground up in the last 23 years. All one man jobs: i.e. me. I've also worked on 3 pre-existing ones that were pretty big. Right now that means a 30 person team with 400 Oracle servers. I NEVER wrote an FRD for the "small" jobs and none of them were failures. On the other hand, the large project I'm a part of now suffers from a LACK of good requirements specs!

So the whole question of writing docs and specs is also dependent on the project: its size, its nature, etc. I assume that Jason is intending that the "Getting Real" approach is for a general class of apps.

My only comment is from my area of experience: with a database-centric app, if you don't focus a lot of attention on a good database model (and a sensible physical structure that follows from the model) then you're going to wind up with an unmanageable mess. I like what Jason had to say because I also hate the (sometimes necessary) process of writing down specs that nobody ever reads anyway. And the approach he outlines is not incompatible at all with my approach of heavy emphasis on the data model (for database-centric apps). But I will say this: you can create a GOOD app with a good database foundation and a so-so UI. But you CAN'T create a good app with a bad database foundation no matter what the UI. The database will eventually turn to crap.

And I'm sorry, the UI is most DEFINITELY NOT the app when it comes to a database project. The data is the app. If the data is crap, then all you have is a pretty illusion.

11 Feb 2005 | Brian said...

Great commentary here.. A few thoughts kept running throug my brain as I read through this thread that didn't seem to be fully addressed:

1. In essence what I take away from this visual, user experience-driven approach to defining/developing applications is that it provides a more effective way for a team of mixed experts/non-experts to share a common bridge of communication - the user experience. This is something any web user engages in on a daily basis - and we all have valid expertise here (my user experience is just as valid as yours). The point is that if an iterating team has something they can more easily relate to, experience together and communicate about, higher quality feedback, insight and requirements can flow out at an earlier stage of the development process.

2. I believe one of the key lessons underneath the first point is that a prototyped user experience allows participants in the iterative process to experience the project as a whole rather than in reductionist chunks required when wading through a 15/20/100 page requirements document - In my experience it very difficult for many people to "grok" the whole of an application through a dense functional spec. Experiencing in "wholes" contributes greatly to the quality of insight and feeback someone can offer..

At the end of the day I'm not ready to say detailed written documentation is not important /valuable for at least some participants in the application development process (e.g. developers themselves). However, it seems to me that is not really the original point being made. Instead, the lesson here is that driving the process of requirements gathering and project definition may be more effectively served through the iterative user-experience process.

Out of this can come greater insight and more clearly defined requirements from all parties involved in the process. And if needed, a much more well informed, insightful, and ass-kicking functional spec doc can also flow out.

happy friday ;-)

11 Feb 2005 | brian west said...

11 Feb 2005 | Doug Lindauer said...

For example, on a database-centric app, if you don't have a good structure, all the pretty front ends in the world won't keep the database from eventually becoming crap. So there darn well better be a major emphasis on creating a good database model up front...

Very true... and by the same token, if the immaculately structured database is built upon a fundamentally flawed user experience, it's inherent value is, to put it lightly, minimized.

I think the big point you overlook is that if a team (internal/ external clients + developers) isn't able to communicate in a sophisticated and clear manner to reach common understanding of/insight into needs, requirements, strategy etc. than the most logically abstracted and efficient database structure in the world will be worth no more than the pixels and files it consists of...

Again the goal here is finding the best path to enable this team of individuals with mixed-skills and priorities to get to the point where a rock-solid database schema can be effectively developed. For many projects, starting with a process to prototype the user-experience is likely to deliver a much higher quality application discovery and requirements defining process then traditional functional specification processes.

With the User Experience prototype locked in and agreed upon, much more interesting and productive development queries can be effectively pursued like "What database structure / application logic will enable us to best deliver this user experience or that user experience". This places the most important player in the process, the end-user, in the drivers seat.

12 Feb 2005 | Gavin Bell said...

I like this approach, the dry, usually never revised functional spec is not a living document. The documents that define the behaviour of most application are the database schema and the user interface.

If you get the user interface wrong, or model the use of the system incorrectly, then the system will fail, as it will not meet the needs of the various end users. If you get the data modeling wrong, then the system will usually not be able to do the things required of it.

Short light documents get read, more than 10 pages usually does not get read. So I try to keep my document short and to the point (I do not always succeed). The big picture document is really important, it gives the framing for what you are trying to do.

Behind this are some other useful documents personas or use cases if you want. You need to know who will use your system and the internal systems if necessary. The user interface needs to meet their needs, all of them. For a lot of web projects the emphasis is on the customer to the site, not the internal staff managing the system, I find that these internal user can get forgotten about.

Whenever I'm designing a system, I agree what we are trying to do for who for first. Then work on drawing out the visual experience for the endusers. Check it is feasible, then iterate again, usually presenting designs for sign off, clients and senior management do not usually want to see database schemas =)

I'm not a visual designer, so I tend to work in wireframes. A more polished visual design or working interface can be made, but it is more important that they know it is achievable. They are usually more successful if you have time to do the entire visual design.

There are interesting overlaps with the scrum methodology in having a full working end to end each month, iterating upon it against the backlog of feature requests.

The most important conversation can be between your dba and the interaction / visual designer. If they are not building the same thing, then you will probably fail.

12 Feb 2005 | Gavin Bell said...

I'm not a visual designer, so I tend to work in wireframes. A more polished visual design or working interface can be made, but it is more important that they know it is achievable. They are usually more successful if you have time to do the entire visual design

I mean that sometimes a wireframe is enough, sometimes you need the full visual design and working prototype. The prototype will raise questions that the wireframes will not address.

13 Feb 2005 | Functional Guy said...

Painless Functional Specs (and why you should write them)

14 Feb 2005 | Ivan said...

This is a rather immature way of understanding sofwtare development. You can not capture an ER model in a UI spec, identify inetgrety contrains, or data flow . UI is not the be all end all of sofwtare design. Further more a func spec is more than the working code, it must be a model that serves as something concrete and mesauarable against which the working systems can be understood an measured. For ui this is slightly differenent. But without a task model how are you sure that the ui adresses the problem space completely and in a verifable manner?

Now a func spec does not have to be a word doc. It can look and be as lightweight as possible. But the notion that you can get away from modeling a problem space before building something that can adress it is simply incorrect. Those models must be explicit. you have to start with the ER in the problem space otherwise you sill not be able to define a constent and clean API that can sustain the abstartced an evloving needs of a customer app. If you don't build elegeance and abstarction in from the beginiing you'll end up with a mess. Just like Microsoft code.

You can not just will away fiundementals of software design.

14 Feb 2005 | David Heinemeier Hansson said...

Ivan, I suppose we must be defying nature, then. Because this is exactly how we work at 37signals. It's how a lot of my fellow craftsmen work on agile projects that I hear about. And, of course, it's widely popularizedby methodologies like Extreme Programming, SCRUM, FDD, and more.

We're not necessarily saying scrap all those other methods, though. We're saying that the screens are the primary driver for delivering our projects successfully. You may or may not need to supplement the screens with other explicit design techniques if some parts are too big or hard to just extract from the screens.

Our natural response when that happens is Less Software. If the screens are not easily convertible into code, change the screens until they are. This doesn't work every time, but more often than you think.

And of course, ER models and data flows are one set of design techniques. Other techniques exist. I enjoy using test-driven development, refactoring, and incremental design as one of my favorite techniques.

Just because you don't design everything up front, doesn't mean that you don't design at all. On the contrary, we design all the time. A little bit every day. As needed.

14 Feb 2005 | Brenda said...

The one-page story is, in a sense, a functional spec. Or a "requirements document". Or a "use case". Or a "scenario". The difference in each is just the level of granularity; they all serve a similar purpose. As user-centered designers, we need to choose the most appropriate vehicle to convey functionality of the system we're going to design, balancing political (business) constraints, audience (client) needs and functional complexity.

That whole "let's tell a story" approach is fine, when you're the consultant, and you have a relatively small set of stakeholders. But when you're an internal "consultant'", tasked with satisfying a huge amount of stakeholders, it behooves you to get black-and-white explicit agreement with as many of those stakeholders as possible. You need to get people to agree to the level of detail relevant to their concerns, which may or may not require writing a detailed functional spec. In my experience, the complexity of the politics correlates directly with the level of detail needed in a spec document; high politics = lots of detail.

Having said that, I don't believe in over-documenting a project, just because you can.

My personal preference is to include functional specs in wireframes. But in highly politically-charged projects, I can't even get to wireframes until a certain number of people agree to what the system is going to do. Going to design without that agreement means rework later, and it would ultimately just be a waste time.

You've talked about your alternative to the design purpose of functional specs, but I don't think you can write them off completely until you suggest an alternative way to deal with the political purpose of functional specs. "Stories" are open to individual interpretation on the part of the audience, and in some cases those are mis-interpretations that don't beome evident until it's too time- or cost-intensive to correct them.

And, FWIW... the interface is *not* the application. Functionality is functionality; some is readily apparent in the interface, some isn't. Starting with visual design as anything more than a rough representation is a mistake; putting lipstick on a pig don't make it Cindy Crawford.

14 Feb 2005 | Randy said...

You've talked about your alternative to the design purpose of functional specs, but I don't think you can write them off completely until you suggest an alternative way to deal with the political purpose of functional specs.

I'm not sure why people keep missing this point. 37signals offered a clear alternative: The interface is the functional spec. Their spec isn't verbal, it's visual. It's the customer experience.

And as far as dealing with politics, the best way to deal with politics is to lessen their impact up front. And I don't know if anything that puts the focus on politics more than a written document that people can point to when something goes wrong or something changes. Putting signatures on things very very early on in the process is a formula for political nighmares later.

14 Feb 2005 | Brenda said...

The above post, of course, should imply that I believe the primary purpose of functional specs is to guide design and development. I called out the political function because I think that's the aspect your approach may not adequately address.

14 Feb 2005 | Arne Gleason said...

And, FWIW... the interface is *not* the application.

Summarizing what Ive been told by those who claim to know (Im still on the fence):

For users, the interface *is* the application (unfortunately theyre most often considered the least important and most unwelcome aspect during functional design). The requirements of users are best served when they can input what they think they need to in a way they want, and get back the result they expect in the way they expected it.

Despite all the gallons of genius (or perhaps GUINNESS) poured into in the guts of your product, if it cant be used, it is useless. But, if it doesnt work its useless! would be the anticipated retort, which is absolutely true (the user expects it to work, right?). Starting by describing what the user expects to see and do cant help but positively feed both efforts, and leaving the user experience to last cant help but result in a less usable product (and sometimes a nearly useless one). Note: Maybe a user centric approach would benifit system-to-system apps or modules as well as it does human-to-system ones (systems could be users to).

17 Feb 2005 | Kevin Cannon said...

On the flipside to that is The Iceberg Secret as noted by Joel Spolsky on Joel on Software

It's worth considering this before going down the route.

17 Feb 2005 | Arne Gleason said...

Iceberg Secret

Dont confuse the customer referred to in this article for the user. The customer in these cases is usually somewhere between not caring and being openly hostile to what users expect. Just watch the look of terror spread across the face of the customer when you suggest you need to talk to a few actual users before design Noooo!!! Thatll wreck everything. WE tell THEM the way things HAVE to be done.

17 Feb 2005 | Michael A said...

Great article. It is the truth, in my experience, that clients need to see something tangable. They should absolutely be part of the expert team planning and developing the project; partners in fact. But they don't want or need to learn more than they have to (would you?). It doesn't dismiss the role of anyone; designer, developer, etc.

It simply points out that our work is transparant when performed at its best. This is Frustrating at times but also gratifying, as many clients consider it "magic" when they see and use an interface that was previously a series of documents (important as well, but more in process). Since the interface is the primary means of communicating with their audience, they want to SEE something. Nothing wrong with that if we all treat each other as equals. Thanks so much.

21 Feb 2005 | Randal Rust said...

Ivan said:

"This is a rather immature way of understanding sofwtare development. You can not capture an ER model in a UI spec, identify inetgrety contrains, or data flow . UI is not the be all end all of sofwtare design."

All too often though, I have worked on projects where the UI design is an afterthought. Reams of flowcharts and use cases do not create a user experience that achieves efficiency and success. Good user interface design does.

Arne said:

"For users, the interface *is* the application"

If you ask me, this is the most accurate statement in this whole discussion. The user doesn't care what's under the hood. As long as data goes in and out and they can do their job, they are happy.

21 Feb 2005 | Davor said...

You are aiming in a good direction with your user-interface-driven specifications though it's only a subset of what should be done. My feeling is that the best approach for specifying user-driven interactive applications is through user manuals of which user interfaces are only a part of. By appropriately using user manuals to capture functional requirements you leverage your work (no separate func. spec. doc) and produce a very good quality user manual which most projects lack anyways. See Dan Berry et. al. for the details on how to use user manuals as requirements specifications.

23 Feb 2005 | Peer said...

Can't we all just agree that there are different types of projects and different types of environments that require different types of working together, and hence different types of documentation? Then again, that wouldn't be much fun.

I LOVE doing minimal specs when I can. Love it love it.

24 Feb 2005 | dzwonki polifoniczne said...

• polyphonic ringtones
• U3.pl
• dzwonki polifoniczne
• gry java
• logosy
• sms
• napisy
• dgs-leichtathletik
• nuty
• dzwonki
• tapety
• gry java
• gsm
• loga
• prepaid
• loga,dzwonki,tapety
• prepaid,generator
• dzwonki polifoniczne
• gry
• logo
• logosy
• polifonia
• polifoniczne
• smieczne
• smieszne
• bramka
• bramka sms
• bramki
• nokia
• nokia dzwonki
• loga dzwonki
• gry java
• dzwonki
• gry
• gryjava
• sms-tapety
• prepaid
• dzwonki polifoniczne
• logo

27 Feb 2005 | Zef said...

Hi Jason - looks like we're on the same wave-length. Just last month I published an article on a very similar topic (putting down design failures to a lack of early interaction design and visuals).

I compared this to a building architect supplying builders with their designs in just words (no blueprints). This would obviously end in chaos, but in the software world we're expected to do this all the time (hence, it often IS chaos!).

Here's the article. I welcome feedback from readers:

I think what you're suggested is a 'designers utopia', but a worthy goal to aim for. Even if functional specs stay - they should at least be 'interaction design heavy'.

At Provoke we produce both an Interaction Spec (with task-flows and UI prototypes), and a Functional Spec (which purely describes the database model, business rules and system-side functions). These are bundled and released in tandem, which seems to work well for our clients.

28 Feb 2005 | Andy Budd said...

Functional specifications documents lead to an illusion of agreement.

Agreed. However from a legal/contractual standpointin the UK at leastyou need to provide a clear definition of your schedule of work. If you don't the client could argue that they thought they were getting one thing when in fact they have been given something else.

Functional specs lead to scope creep from the very start. Theres very little cost in saying yeah, ok, lets add that to a Word document.

True. That's why you need a good project manager rather than a yes man that agrees to every client request. Conversely, if you don't define the scope in the first place, everything is scope creep.

Functional specs are about making decisions before you have enough information to decide. They are about predicting the future and we all know how accurate that is.

This is true to a certain extent. However functional specs should be a living document, rather than something that's written and then filed.

We write a one page story. Then we begin building the interface the interface is the functional spec.

True. I think wireframing as much of the site as possible is the way to go. However it's much easier to change things on paper than it is to change designs and HTML.

04 Mar 2005 | Justin said...

I would love to have a look at the Basecamp or Tada-List written one page story. Do you get a copy at the workshop?
-Justin