Specified to Death

Robert's Blog ideas about design and development

<< Design is not an Agile dirty word | Home | Ever consider that we are too good at what we do for our own good? >>

Specified to Death

Comments (6) | Share

Documents don't kill understanding. Documents in our American culture kill understanding.

Why do people who specialize in bending words forget to transfer meaning?

The problem with lengthy requirements documents are

They never tell the whole story no matter how much you write
The users of these documents (programmers) never ask any questions because its all right there in the spec
The writer of said document never questions if his intent was understood because its all right there in the spec

Conversations leading to acceptance tests are better for specifying a project because:

Conversations don't inspire us to use 25 cent words that even we are fishy on the meaning of
You are more likely to ask a question of a person than you are of a piece of paper
Understanding is best reached through a series of questions asked and answered than a document read over ten times

Dan say's its ok to use functional specs and use cases to organize your thoughts. I agree with him if these things are for your eyes only. I wasn't born in 1950, and I haven't watched "Tron" enough times to be able to think in terms of "the system shall..."

In Joel's perfect world, functional specs can be used to communicate design. Joel, I think you may be the only person on earth who can pull this off.

I like user stories and acceptance tests for communicating design because:

They are light-weight enough not to kill conversation
They allow you to focus on only what matters right now

Aren't there published studies to the fact that most human brains can only deal with 3-5 pieces of information at a time?

This does not mean that I am advocating throwing out design and design review. What is does mean is that I strongly advocate doing Just In Time Design.

Posted on Thursday, July 10, 2008 12:40 AM | Back to top

Comments on this post: Specified to Death

# re: Specified to Death

A design is simply a hypothesis on how a particular technology might solve a human need. How best to communicate this hypothesis depends on several factors? The biggest drawback to paper forms of communication is the relatively low bandwidth as compared to face-to-face communication.

The important part of designing is to always realize that the result is always a guess at a possible reality. The only way to test your design is to actually implement it and a design is hardly ever perfect so the implementer must have enough design skill to be flexible to changing the design when the code "speaks" to him.

My point really is that saying in general that face-to-face is better than written communication is wrong and goes against thousands of years of scientists and philosophers writing down their hypotheses. The difference between software and science mainly is that the hypothesis has much more value in science. Once a design has been implemented the value of the communication of the design drops dramatically.

I also find it ironic that I am writing this to you even though I am currently 15 feet away from you. ;-)

Left by Kyle Marshall on Jul 10, 2008 8:40 AM

# re: Specified to Death

The devil is in the details. While you can express intent more fluidly with direct communication, it's the little things that get passed you if they are not documented. It is extremely probable that after an hour design discussion, developers are very likely to forget some obscure request that was brought up at the beginning of the discussion if it isn't documented somewhere.

Left by Jae on Jul 10, 2008 9:15 AM

# re: Specified to Death

Minutia is more than likely the result of technological constraints than anything else. If you feel constrained by technology, you are probably doing something wrong.

Specification is supposed to be about specifying behavior not interfaces between client and server. Those contracts are technological problems and should be handled at the level of technology (i.e. SMD, SOAP, interfaces, etc).

Requirements documents should be for the customer, not the technologist.

Left by Robert Stackhouse on Jul 10, 2008 9:41 AM

# re: Specified to Death

It took a moment for me to catch why you related requirements specs to design. I've certainly worked in environments that used good practices to ease the transition between functional spec and design but never in one where the functional spec actually called out the design the way Joel claims it could/should.

I really respect Joel because he writes a lot of great content and seems to really believe in what he does. That said, I only actually agree with him about 50% of the time. About 25% of the remainder I find myself thinking he is just plain wrong. This is one of those times.

A functional spec should not be written to require a particular design. It should be written to so to at least strongly imply how the the developed result can be verified to do what was intended. This can be through documents (often painfully for the reasons you list and for others), through conversation, or through "executable requirements" such as those the BDD folks (FitNesse, rSpec, etc.) write. Personally, I choose a combination with as much emphasis as possible on the latter two.

Left by Mike Abney on Jul 10, 2008 2:32 PM

# re: Specified to Death

Functional specs are given a bad rap because they are un-maintained. I am in the process of passing over ownership of code for 12 projects which I have worked on. I insisted on design specs of front, but as each of these projects progressed, scope creap set in. Changes were made left and right, all through emailed requirements. We had to give estimates for these changes, but in an effort to keep the estimates within reason, or to keep actuals close to the estimates, the specs were never updated. Now I am in the process of passing ownership, and my co-worker that it taking it on wants to understand how they work. Put yourself in this situtation (either side of it), and you will realize why documentation is extemely important, and why all estimates should include time to do documentation, and keep it up to date.

Left by John Workman on Jul 10, 2008 9:57 PM

# re: Specified to Death

@John, I don't personally believe in expressing direct "ownership" of a software project. I don't believe in coding alone either. I think that the meat of your problem stems from the fact that it looks like someone told you to go code in a closet. What kind of applications have you written? Were they web-based? Simple? Complex? Were you allowed any direct contact with the end user (we can already tell you weren't allowed direct contact with the customer/stakeholders)? In my observation, scope creep is just a customer or a manager trying to squeeze more money out of the same old application. For example, I was good with Office 2003. Did I need Office 2007? No. Did it get forced on me anyway? Absolutely. When you see scope creeping in, you should fight like hell to push it back. I should also point out that there is a world of difference between missing features and scope creep. If 90% of your user base say that your application is "missing something", it is time to go figure out what that something is. One should also note that a request to make something perform better than it already does in the areas of speed, usability, aesthetics, or reliability is not scope creep. It is just the world expressing their discontent with your creation.

Left by Robert Stackhouse on Jul 24, 2008 12:30 PM

Your comment:

Title:

Name:

Email: (never displayed) (will show your gravatar)

Website:

Comment: Allowed tags: blockquote, a, strong, em, p, u, strike, super, sub, code

Enter the code shown above