Writing a Software Requirements Document

1 Writing a Software RequirementsDocumentTanya BerezinTable of ContentsSHOULD YOU READ THIS PAPER?3 WHAT IS A Requirements Document ?3 WHY BOTHER WITH A Requirements Document ?4DO I HAVE TO WRITE A Requirements Document ?5 WHO USES THE Requirements Document AND WHY?5 GENERAL PRINCIPLES IN Writing A Requirements DOCUMENT6 SECTIONS OF A Requirements DOCUMENT9 PART I APPLICATION OVERVIEW10 PART II FUNCTIONAL REQUIREMENTS12 PART III APPENDICES15 WHO NEEDS WHAT? SUMMARY OF PURPOSE AND USAGE OF THE SECTIONSOF THE Requirements DOCUMENT17 HOW TO GET OTHERS TO READ THE Requirements Document ?18 REFLECTING CHANGES IN REQUIREMENTS19 DOCUMENTING REQUESTS FOR ENHANCEMENTS20 TRACING REQUIREMENTS21 CONCLUSION AND FURTHER READING21 AUTHOR BIOGRAPHY22 Should You Read This Paper?By: Tanya BerezinDocument: Writing a Requirements DocumentModified:June 14, 1999 File Name: C:\My Documents\PROJECTS\ \ Requirements \ 3 of 23 Should You Read This Paper?This paper discusses the purpose and contents of a Requirements Document fora business application.

2 It is an introduction to the subject and will be mosthelpful to you if any of the following applies to you: you are responsible for collecting Requirements for a business application you are leading a business application development project you are not sure what a Requirements Document ought to look like or even ifyou need one you are not sure what to do with a Requirements Document even if onemiraculously appeared on your desk tomorrowThis paper will help you write a professional Requirements Document . Once youfeel you understand what a Requirements Document is, I urge you to startreading more advanced material; some of the books are listed at the end of you are an experienced Requirements analyst and/or project manager youmay want to skim this paper to see if you can add any of the information here toyour own bag or tricks . You also may want to review the bibliography at theend of the paper to see if you have missed any of the great books listed Is a Requirements Document ?

3 The Software Requirements Document is a written statement of what thesoftware will do. This seems quite a dull statement but it is worth examining abit closer. Requirements Document states what the Software will do. It does notstate how the Software will do the Software does is directly perceived by its users either human users orother Software systems. When a user performs some action, the softwareresponds in a particular way; when an external system submits a request of acertain form, it gets a particular response. Therefore you and the users mustagree on actions they can perform and response they should expect. Thiscommon understanding is captured in the Requirements the Software responds to the agreed upon request is not addressed in therequirements Document . For example, the Requirements Document does notinclude screen layouts, database schemas, descriptions of communication layers in short, no statements of design of any sort.

4 For example, it is a requirementfor a word processing application to be able to open an existing file. It is adesign issue whether to build a customized file selection tool or use a platform-standard file selection is not to say you won t seek users input on some of the design, mostespecially on user interface design, but it is very important to recognize andWhy Bother with a Requirements Document ?By: Tanya BerezinDocument: Writing a Requirements DocumentModified:June 14, 1999 File Name: C:\My Documents\PROJECTS\ \ Requirements \ 4 of 23respect the boundary between the statement of Requirements and howrequirements are implemented. Design is the responsibility of the developmentteam they should be free to choose the most appropriate way to satisfy allaspects of the Requirements features, performance, usability, etc. Usually themost appropriate way is the most simple way but sometimes otherconsiderations may affect design decisions such as opportunities for design orcode reuse, for example.

5 Requirements Document is a written Requirements Document is not a collection of notes and Post-It s, e-maildiscussions, or accumulated knowledge in someone s head. They all are usefulas supporting information but they cannot be distributed easily for review can give a written statement to other people to read and discuss. Thedocument can serve as the basis for an agreement between you and yourcustomers and it can be used by the developers and testers to implement theapplication and verify that it meets the original agreement. There are manygreat things you can do with a written Bother with a Requirements Document ?The answer is (or ought to be) pretty obvious: if you haven t written down whatthe application is supposed to do, how will you know what to develop and howwill you manage your customers' expectations?Obvious though the need may seem, you often will have to preach the gospel ofrequirements documentation far and wide in your organization unless yourcompany already follows mature development practices.

6 Even if your ISorganization does not need convincing, your customers (either internal orexternal) may wonder if you are wasting their time and money Writing arequirements Document when you really should be coding! The main purpose of a Requirements Document is to serve as anagreement between the developers and the customers on what theapplication will many cases this agreement is enforced via a legally binding contract. Even ifthis is not the case for your application, I strongly recommend you view therequirements Document as a contract between you and your , you should strive to instill the same attitude among your everyone treats the Requirements Document as a Software developmentcontract, all parties are more likely to have common expectations for theapplication a very necessary thing for your project to Requirements Document brings the following additional benefits: the customers can see early on if their needs will be met the developers can estimate the effort involved in creating the application the development project leader has a basis for a project plan the quality assurance people have a basis for testing the applicationDo I Have to Write a Requirements Document ?

7 By: Tanya BerezinDocument: Writing a Requirements DocumentModified:June 14, 1999 File Name: C:\My Documents\PROJECTS\ \ Requirements \ 5 of 23Do I Have to Write a Requirements Document ?In case the previous section did not quite convince you that you need arequirements Document for your next application, this section offers a simpletest that will tell you if you must write a Requirements Document or you can wing it .It is true that in some cases you can get away with not having a formalrequirements Document : if your application is small enough to be developed bya single person and the user population is also very small (a few people or asingle workgroup). When this is the case, it is possible to achieve a commonunderstanding of what the application will do without committing theknowledge to paper. In all other cases you really need a written requirementsdocument. You must have a Requirements Document if any of the following is truefor your application: it will take more than about a calendar month from conceiving theproject to putting in into production more than one person will work on the application more than one workgroup will use itWho Uses the Requirements Document and Why?

8 There are many distinct roles in each Software development project. While thesame person often plays more than one role on a given project, it is most usefulto consider how every role on the project uses the Requirements I list the project roles and the reasons for each role to use therequirements Document . Remember that each of these roles uses the documentin a different way; indeed some may use only some parts of the we discuss the structure of the Requirements Document in later sections Iwill point out which roles primarily use each section of the in a Software DevelopmentProjectReason for Using the RequirementsDocumentDevelopment Project Leader Scope the project; divide the project inphases Obtain agreements from the businessexpert, project sponsor, and thedevelopment manager on the scopeand schedule for phases Track development progressRequirements Analyst Elicit and Document businessrequirements Test the application against therequirementsGeneral Principles in Writing a Requirements DocumentBy: Tanya BerezinDocument: Writing a Requirements DocumentModified:June 14, 1999 File Name: C.

9 \My Documents\PROJECTS\ \ Requirements \ 6 of 23 Development Team Member Design and code the applicationQA Specialist Verify that application conforms torequirementsUser Documentation Specialist Produce user documentationLegacy Support Specialist Support legacy integration needs of theprojectMaintenance Team Member Learn the application to take over theproduction support from thedevelopment team Support users in productionDevelopment Manager ( , theperson to whom the developmentproject leader reports) Understand planned phases andcoordinate with the development ofother applications Track development progressProject Sponsor Provide the motivation for the project Sign off on the planned phases andtheir scopeBusiness Expert (oftendesignated by the projectsponsor) Confirm that the Requirements reflectthe business needs Sign off on the planned phases andtheir scopeGeneral Principles in Writing a Requirements DocumentThe previous three sections have given you the motivation to produce arequirements Document : you know what purpose it serves, what benefits itoffers, when you absolutely must have one.

10 You found some users for it so youknow it won t gather dust on a we will consider what a Requirements Document looks like but before wedive into details I will introduce some general ideas that you should have inmind while working on a Requirements Unnecessary WorkFirst I d like to state an idea I call the Least Work Principle: Do not do any work that costs you more than it is worth to principle is very general and it requires conscious interpretation in everywork situation to be useful. For example, I always clear my desk before I leaveoffice for the day because seeing a desk piled high with papers first thing in themorning ruins my mood for the rest of the day. For me the Least Work Principlein this situation dictates to put stuff away at the end of a day. Most peopletolerate a messy desk just fine (in other words, a tidy desk is worth nothing tothem) so quite correctly they do not spend any time cleaning it. They may notGeneral Principles in Writing a Requirements DocumentBy: Tanya BerezinDocument: Writing a Requirements DocumentModified:June 14, 1999 File Name: C:\My Documents\PROJECTS\ \ Requirements \ 7 of 23even know it but they apply the Least Work Principle when they leave theirdesk is how the Least Work Principle applies to Writing requirementsdocuments.