= The Story of the Paperclip: Writing Good Functional Requirements =

== The Humble Paperclip ==

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: 

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

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:

<file>
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!
</file>

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.

{{ :processes:gold_star.gif|}}

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 [[/articles/building_widgets_business_vs_technical_requirements|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.
== Good Requirements: Five Rules Of Thumb ==

 * **Keep It Simple.** I can’t overemphasize this one. \\ \\ People (at least us Americans) don’t like to read.  This is why most ads have one sentence. Two at most. Even the ads that have lots of words just use them for decoration. The real message is in the one or two words they’ve highlighted. \\ \\ By not putting in too much detail, you increase the odd that your programmers, graphic designers, executive staff, and others will actually read your spec. Not just open the file, say to themselves ‘looks like you’ve thought of everything’ and dash off a quick note saying ‘thanks for all the hard work’. Generally, such notes are followed a few weeks or months later by much another wondering where XYZ is. \\ \\ Putting in too much detail can also sap the creativity of your programmers. Put yourself in their shoes. What if you got some ten page manifesto dropped on your desk that described how the print button was supposed to work, including every last little detail about what to do if the document is too long, too short, contains pictures, is too wide, etc. Just tell them they need to put a print feature in, and that it should be able to print all documents created by the program or gracefully error out, and you’re done.\\ \\ 

 * **Use Pictures.** They say a picture is worth a thousand words. Could be true in this case. Creating wireframe interface mockups is one of the best ways to show people what the program will do. \\ \\ Even better is to hire a graphic or UI designer and get them to create prototypes of the actual screens. You’re going to have to do this at some point anyway, and getting it done now can save a lot of time in the end.\\ \\

 * {{ :processes:five_rules_of_thumb.gif|}} **Circulate Requirements Early and Often**, and set hard deadlines for feedback. This is one of the more controversial ones. I believe that it is a good idea to circulate your requirements ‘early and often’ to get feedback, and then set hard deadlines for that feedback (e.g. If I don’t hear from you by Tuesday at noon, I’m going to assume that you think everything is OK). \\ \\ The goal is to get all the stakeholders in a project to buy in. The problem is that everybody else is just as busy as you are, and its easy to ignore a document, especially if it’s the third revision they’ve seen and they’re leaving for New York in two hours. \\ \\ One technique I’ve seen used successfully is that of the product design meeting, where you setup a meeting to go over the requirements (or a section of the requirements) and make sure to invite everybody that needs to be there. You tell them that if they don’t show (or otherwise comment), then they don’t get any input. \\ \\ Of course, the tough talk is hard to enforce when someone does come back three weeks later and say that you absolutely must have XYZ feature. Its particularly hard to enforce when ‘someone’ happens to be your boss. I’m still looking for the perfect solution.\\ \\ 

 * **Use Bullet Points.** Some people I know even use PowerPoint, not Word. It gets back to the ‘American’s don’t read’ credo. People do seem to respond better to bullet points. \\ \\ I really like a bullet point format where you highlight everything critical in the bullet point, and then write the rest in paragraphs later. Give me the bullet point, and if I’m interested in the details I’ll read it.\\ \\ 

 * **Keep It Organized.** Group requirements by functional areas of the program, and put in section headings, table of contents, etc. don’t automatically assume that somebody will read the entire doc. \\ \\ Point of fact: you will likely be the only one to read your doc cover-to-cover, particularly if its for a large system. Everyone else will skim through the features or sections that they care about, or are responsible for, and just skim the rest. Make it easy for them.\\ \\ 

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 [[http://www.joelonsoftware.com/articles/fog0000000036.html|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.//