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.