Quick Nav
The paperclip was invented in the 1890s, and has been around, more or less unchanged, for the last hundred years. It isn’t likely that anyone created a requirements document for the paperclip, but I sometimes like to think of what it would have looked like if someone had.
It could have been about two sentences:
PAPER BINDING DEVICE REQUIREMENTS Design a device that binds two or more sheets of paper together without damaging them. It should be simple to use, lightweight, reusable, inexpensive and easy to manufacture.
Then, after a shot or three of Jim Bean, I think about what the document would look like if some of the people writing software requirements today had written it:
PAPER BINDING DEVICE REQUIREMENTS BACKGROUND Global Amalgamated Worldwide Design (GAWD) has been commissioned by OmniCom International to design a device that will allow the user to hold one or more pieces of thin material (e.g. paper, transparencies, etc.) together. This document outlines the purpose of the project, the target market, as well as all functional requirements. It is intended to be read by GAWD designers, project managers, and executives, as well as OmniCom project managers and executives. PURPOSE The purpose of the project is to design a device that will allow the user to bind, or otherwise join, two or more sheets of thin material together. Specific requirements of the device are outlined below, in the Functional Requirements section. TARGET MARKET The target market for this device is anyone that has two or more sheets of thin material to bind together. This may include office workers, home users, construction workers, service personnel, or others. FUNCTIONAL REQUIREMENTS * The primary requirement for the device is that it be able to bind, or otherwise join a minimum of two, and a maximum of fifteen, sheets of similar thin material together. * This material may be made of anything, but the thickness of the material will not exceed 0.1mm/piece. The height and width of the material shall not exceed 216mm by 279mm. * The device should not damage the material in any way in the binding process. * The user of the device should be able to use it quickly, in two seconds or less. * The weight of the device should not exceed one gram. * The device should be easily reusable at least three times. * The device should cost less than $0.01 to manufacture in volume. ADDITIONAL ITEMS * The scope of this project includes only the design of the device, not the design of its manufacturing process. However, designers should put some thought into the process for manufacturing, to ensure easy of manufacturing. * If you've read this far, you get a gold star -- but I bet you didn't!
Is the second requirements document more complete? OK, you've got me there. But is it really better? Not really, because it puts serious limits on the creativity of designer, and its long enough that people may not read all the way through it. It might be useful if you were designing something for the government, but for just about all other projects, its overkill. And it took me twelve times as long to write the second doc as it did the first.
So if you’re tasked with writing requirements for a paperclip, or perhaps software, how do you write requirements that are complete enough that they convey the needed information, but simple enough that people actually read them?
Before we get to the good stuff, a quick interlude: common wisdom has software teams writing two types of requirements, business/functional requirements and technical requirements. (Not sure what's what? There's an entire article on that). Most of these tips are aimed more at the business/functional side, so if you're on the technical side, take this with a grain of salt.
That’s it. Now go forth and write!
N.B. It should be noted that there are other schools of thought on writing specs. For example, Joel Spolsky says in Painless Functional Specifications that you should write in ‘mind numbing detail’. I don’t agree with him, but its always good to consider multiple viewpoints before you make a decision.
Discussion
Hmmmmm…
I absolutely get your point about keeping things simple. Boy it would be nice to be able to do that. Unfortunately it never really works that way in the real world. I like your initial statement:
“PAPER BINDING DEVICE REQUIREMENTS
Design a device that binds two or more sheets of paper together without damaging them. It should be simple to use, lightweight, reusable, inexpensive and easy to manufacture.”
I think that that is almost a great “Business Requirement” with the exception that it doesn't say what value such a thing would hold. You'd think, also that anyone should be able to understand “simple to use, lightweight, etc”. but they don't.
“Simple to use” works fine if your target customer can get the idea of how to use it and has the facilities (e.g. hands, fingers, sight) to do so. It doesn't quality “simple”. It's irratating to me, at least, that your statement wouldn't be obvious but people find a way of making it not so. Sort of like the people that had to add “Don't use while in a bath tub full of water” on blow dryers. Unfortunately we have to account for what I would call the “duh” factor.
“Lightweight” could also be a problem. Have you ever noticed that documents stapled together don't tend to fall off a desk as quickly as those paperclipped together? Now that might very well be because of where the paperclip was attached to the document - hence, we need a technical requirement identifying this issue (that's assuming that the risk issue of “falling of the desk” is a critical one).
I know this is nit picky but, quite frankly, until you've worked with engineers (of pretty much ANY kind) you just won't get it.
Roderick-
Thanks for your comments. I actually have worked with a lot of engineers (and am one myself), and I think you're not giving enough credit to engineering staff. In my experience, you only need that level of detail if you're trying to do something with an offsite/offshore team, and even then you're bound to get pretty mediocre results.
If you give engineers some direction, help them understand the problem and then let them run with it, I think you come up with better solutions more quickly than you would otherwise.
Of course, this is predicated on having a group of good engineers… if your team is the 'I hate my job and I leave right at 5pm' type, then you're probably not going to get very far no matter what you do.
David
”…a device that binds two or more sheets of paper together without damaging them. It should be simple to use, lightweight, reusable, inexpensive and easy to manufacture.”
This describes clipboards, blue tac, fridge magnets, folders and 1,000-page-per-minute industrial binding machines.
Not one of the things you identify would be an adequate requirement. “Simple to use” is so subjective it's meaningless - especially when you apply it to IT systems - what's simple to an experienced engineer will almost always be difefrent from what's simple for a novice end user in customer service, for example.
“Lighweight” is completely relative. 600 Kg may be very lightweight for an insustrial binding machine. Not so for a paper-clip.
Is a tube of glue “reusable”? Is a machine that requires topping up with supplies? “Inexpensive” depends totally on your perspective. “Easy to manufacture” is equally useless.
Sorry to sound negative - but I wouldn't want any inexperienced person looking for useful information to come across this page and believe that the best way to write requirements is with a a brief statement of vague, unmeasurable, subjective aspirations. It's not.
In fact, this advice is absolutely the opposite of the best way to write requirements - and it's a clear example of why so many customers are left so unhappy by IT projects.
Requirements should be unambigous, clear, specific, measurable and propoerly thought through. Otherwise the custmer will not get what they need - even if the developer does have more fun on the way
I agree with Roderick - you must include the detail regardless of the location of your engineers. It is critical to avoid mistakes down the road. As a technical writer, my rule of thumb is to never assume knowledge.