Last Updated: 19 Nov 2023
|
Differences
This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision Last revision Both sides next revision | ||
processes:writing_good_functional_requirements [Jun 19, 2008 05:49 PM] dordal |
processes:writing_good_functional_requirements [Nov 13, 2023 04:07 PM] 111.225.148.156 removed |
||
---|---|---|---|
Line 1: | Line 1: | ||
+ | = 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: | ||
+ | |||
+ | < | ||
+ | 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, | ||
+ | </ | ||
+ | |||
+ | 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, | ||
+ | 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 | ||
+ | | ||
+ | * This material may be made of anything, but the thickness of the material will not exceed | ||
+ | | ||
+ | * 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, | ||
+ | * If you've read this far, you get a gold star -- but I bet you didn' | ||
+ | </ | ||
+ | |||
+ | 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, | ||
+ | |||
+ | Before we get to the good stuff, a quick interlude: common wisdom has software teams writing two types of requirements, | ||
+ | == Good Requirements: | ||
+ | |||
+ | * **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, | ||
+ | |||
+ | * **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.\\ \\ | ||
+ | |||
+ | * {{ : | ||
+ | |||
+ | * **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, | ||
+ | |||
+ | 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:// |