Home

User's Manual as a Requirements Specification: Case Studies

1. Parnas D L and Clements P C A Rational Design Process How and Why to Fake It IEEE Transactions on Software Engineering SE 12 2 p 196 257 February 1986 POSIX IEEE Standard Portable Operating System Interface for Computer Environments IEEE Std 1003 1 1988 Technical Committee on Operating Systems of the IEEE Computer Society 1988 Anonymous Ravid A A Method for Extracting and Stating Software Requirements that a User Interface Prototype Contains M Sc Thesis Faculty of Computer Science Technion Haifa Israel March 1999 Available at ftp www cs technion ac il pub misc dberry alon ravid Thesis doc Shpilberg F WD pic A WYSIWYG Direct Manipulation pic M Sc Thesis Faculty of Computer Sci ence Technion Haifa Israel July 1997 Siddiqi J and Shekaran M C Requirements Engineering The Emerging Wisdom IEEE Software 9 2 p 15 19 March 1996 Sommerville I and Sawyer P Requirements Engineering A Good Practice Guide John Wiley amp Sons Chichester UK 1997 Swartout W and Balzer R The Inevitable Intertwining of Specification and Implementation Communi cations of the ACM 25 7 p 438 440 July 1982 van Lamsweerde A Requirements Engineering in the Year 00 A Research Perspective in Proceedings of 22nd International Conference on Software Engineering ACM Limerick Ireland June 2000 Weidenhaupt K Pohl K Jarke M and Haumer
2. With enough demonstrations of the effectiveness and cost benefits of the approach perhaps more projects can be persuaded to adopt this approach as an effective compromise between the extremes of having no requirements process at all and having a full fledged heavy weight requirements process producing both an SRS and related docu ments and a user s manual While industry is wary of jumping on yet another methodological bandwagon YAMB it does adopt techniques that are repeated demonstrated in practice to be effective such as inspection 15 Perhaps with enough studies like this one showing clear success stories the user s manual as RS approach will be well adopted 9 Threats The reader should remember that these case studies of writing requirements specifications in the form of user s manuals are just that case studies Certainly each case study was a success in that the writing of the user s manual helped focus requirements elicitation and analysis the writing of the user s manual forced consideration of user needs in the product and in its requirements the user s manual provides a covering set of test cases in each case in which the product has been delivered the user s manual describes the product completely in each case in which the product has been delivered the customer is satisfied with both the end product and the match between the manual and the product in one case the user s manual helped the program
3. ON Canada 2001 Boehm B W Software Engineering Economics Prentice Hall Englewood Cliffs NJ 1981 Boehm B W and Ross R Theory W Software Project Management Principles and Examples EEE Transactions on Software Engineering SE 15 7 p 902 916 July 1989 Breitman K K Evolu o de Cen rios Scenario Evolution Ph D Dissertation Departamento de Informatica Pontificia Universidade Cat lica Rio de Janeiro RJ Brazil May 2000 Brooks F P Jr The Mythical Man Month Essays on Software Engineering Addison Wesley Reading MA 1975 Carroll J Rosson M B Chin G and Koenemann J Requirements Development in Scenario Based Design IEEE Transactions on Software Engineering SE 24 12 p 1156 1170 December 1998 Carroll J M Scenarios and Design Cognition pp 3 5 in Proceedings of the IEEE Joint International Requirements Engineering Conference RE 02 IEEE Computer Society Press Essen Germany 2002 Davis A M Software Requirements Analysis and Specification Prentice Hall Englewood Cliffs NJ 1990 DeMarco T The Deadline Dorset House New York NY 1997 Dorr J Kerkow D von Knethen A and Paech B Eliciting Efficiency Requirements with Use Cases in Proceedings of Ninth International Workshop on Requirements Engineering Foundation for Software Quality REFSQ 03 Klagenfurt Velden Austria 16 17 June 2003 Fagan M E Advances i
4. there were only minor rewriting and no restructuring Thus instead of spending 2 months specifying and then 7 months implementing and testing she spent 5 months specifying and then only 4 months implementing and testing By spending 3 months more than planned writing an RS that satisfied a particularly hard nosed customer who insisted that the manual convince him that the product already existed Ou managed to produce an RS that had very few errors and that was very straightforwardly implemented That is there were no show stopping surprises that would cause a major restructuring or rewriting It helped that Berry the customer knew pretty much what he wanted and did not want from his experience with one prototype and 3 other RSs Almost all the errors found by testing were relatively minor easy to fix implementation errors The two requirement errors were relatively low level and detailed and involved subfeatures in a way that required only very local changes to both the manual and the code Particularly helpful was that all the exceptional and variant cases had been worked out and described in the manual Thus there was very little of the traditional implementation time fleshing out of exceptional and variant cases and the traditional implementation time subconscious requirements engineering Consequently Ou found the scenarios including exceptions and variants that were in the manual to be a complete set of black box test cases so much so t
5. 14 The analysis team found that having an RS in the form of a user s manual made it easier than normal to work with the customer to address potential human computer interface issues Normally a problem with this interface would not even be detected until after the system were implemented This benefit is important in an application for which there is little prior experience with its user interface as is the case with VUI The developers find the user s manual easy to work with as an RS Some of them are new to the group The user s manual form of the RS has made it easier for the new members to get up to speed Having both the user s manual and the prototype has reduced the learning curve by at least 50 over having only a traditional SRS Indeed the developers have gotten into the habit of calling the user s manual the specification 7 Lessons Learned In the course of the experiences described above and others a number of lessons were learned They may be classified into five different groups advice on writing user s manuals in general and as RSs special kinds of user s manuals why user s manuals work as RSs requirements engineering processes aided by writing a user s manual and other software engineering processes aided by writing a user s manual Sed ae This section is divided into 5 subsections one for each group of lessons 7 1 Advice on Writing User s Manuals We learned some specific lessons a
6. P Scenarios in System Development Current Prac tice IEEE Software 15 2 p 34 45 1998 Wolfman T flo A Language for Typesetting Flowcharts M Sc Thesis Faculty of Computer Science Technion Haifa Israel 1989 Wolfman T and Berry D M flo A Language for Typesetting Flowcharts pp 93 108 in Electronic Publishing 90 ed R Furuta Cambridge University Press Cambridge UK 1990 25
7. cases These should be the same scenarios and use cases that describe how users exercise the CBS to do their work These scenarios and use cases in turn form a good basis for building test cases that cover the expected ways the CBS will be used 29 Moreover since the users are guided by the user s manual in their uses of the CBS these test cases provide a good coverage of the expected uses of the CBS Finally if there are different kinds of users of a CBS e g ordinary application users and system maintainer users then a different user s manual should be written for each kind of user addressing the way he sees the CBS These user s manuals specify differing possibly overlapping sets of functions for the CBS 3 Motivating the Writing of a Requirements Specification Writing a good RS for a CBS is difficult it delays getting on to coding and it is considered a waste of time This section considers several ways to motivate writing an RS for a CBS and overcoming these inhibitions 29 Some but not all of these ways involve writing a user s manual as the RS Writing a good RS for a CBS is difficult because the advice to describe only what the CBS does without con straining how the CBS does it is easier said than done Clients and users tend to describe solutions to possibly non existent problems rather than just problems that need to be solved 18 Consequently requirement analysts who are not domain experts tend to think about
8. is still possible to generate test cases from the usage descriptions found in the user s manual More generally scenarios or use cases can be used to generate test cases A little thought shows a fundamen tal equivalence between scenarios and test cases Both must cover all possible inputs and uses of the CBS under consideration i e the CBS under design or test Obtaining this full coverage is hard The literature on testing abounds with proof of this difficulty 3 20 22 Indeed after flo had been used about a year with no problems an input was given that flo drew incorrectly collapsing two boxes into one with their interior texts overwriting each other Without going into too many details the input involved nested conditionals It turned out that Wolfman and Berry had never tested that particular input or any of the infinitely others that showed the problem There were no such examples in the manual In retrospect it is hard to imagine not having nested conditionals as a scenario or as a test case if the goal is complete coverage How ever neither of them ever thought of it Perhaps they did not view this as a special case because we had tried other forms of nesting Moreover it is so common that no one else thinks of it as very special The bug showed up one day when they were using flo for a production job Completeness of scenarios and completeness of test cases are tough to achieve very tough There is an added benefit of deri
9. manual that were indicated by discoveries made during attempted use of the features described in the manual to write a changed manual The three steps were repeated until they arrived at a manual and an implementation for which all implemented features were described in the manual all features described in the manual were implemented and the customer and user Berry was happy with the features and their output As a bonus there was available at all times during the implementation a nice built in test with full feature coverage the manual itself From the similarity in the structures of the papers and manuals about eqn pic grap dag and flo it appears that the same approach was used by Kernighan Bently Cherry and Trickey to design and implement eqn pic grap and dag During the development the manual underwent many many iterations Any time Berry did not understand what it was saying he complained Any time he could not see the purpose of something he complained Many times something it said suggested to him another option Many times something it said led to his asking how to do something related gt Appearances can be deceiving Berry once gave a talk about flo to an audience that included Brian Kernighan an author of pic Berry asked Kernighan if this approach was used to design and implement pic Kernighan replied No Wolfman had to fix each of these problems sometimes by changing or extending
10. s current time and the user s future Everything happens in the specifier s future 7 1 3 When How Information is Needed in Specification Recall that we are admonished to specify What not How when giving an RS for a CBS Specifying only What allows the implementers the greatest freedom to choose an implementation a How However several have noted that sometimes it is necessary to give some details of the How usually what is now termed Architecture 47 5 38 37 One example is that of Knuth s exposure of the line breaking algorithm for TEX in The T Xbook 32 which serves as both the RS and the user s manual Knuth described the algorithm in the RS and user s 15 manual for two main reasons 1 to ensure that all implementations of TEX produce the same formatted output even down to the line breaks and spacing between words and 2 to give the user enough smarts about the line breaking algorithm that he can exercise the commands to effectively achieve the desired line breaking and interword spacing That the RS of TX is its user s manual seems to have served as a powerful filter to make sure that a How detail showed up in the manual only when the detail is necessary for the user s effective use of TEX 7 1 4 Prototyping Helps Write User s Manual Sometimes in order to write a user s manual the requirement engineer has to prototype or at least mock up the screens so that she can get the nice screen pict
11. size up to 10MB These details may be appropriate for the bragging section or for the system requirements section Even if some nonfunctional requirements of a CBS are not appropriate for specification in a user s manual it is still useful to specify the CBS s functional requirements with a user s manual especially if the CBS is user cen tered Should it be necessary to specify nonfunctional requirements then a separate companion SRS can be written for just the nonfunctional requirements In any case no matter where the nonfunctional requirements are specified the functional information in the user s manual that is the use cases may be usable to help identify efficiency and other nonfunctional requirements 14 6 Case Studies This section describes case studies by the authors using the user s manual for three different CBSs as the RSs for those CBSs 1 The first case study for the development of flo is by Berry based on his experience supervising a master s thesis years earlier A The second case study for the development of WD pic is by Berry based on his experience supervising another master s thesis years earlier by Berry Daudjee Dong and the Nelsons based on their experiences in a graduate Requirements Engineering Seminar and by Ou based on her experience doing her master s thesis under Berry s supervision 3 The third case study for the development of ExpressPath is by Fainchtein based on his e
12. the language and almost never reducing the language In one case he threw out a whole collection of attributes short tall etc in favor of setting the size of bubbles around nodes bubbles turned out to be a simple way to specify completely the compact ness of the layout The iteration continued until Berry could think of nothing wrong and nothing more to add For more details please consult Wolfman s thesis 50 or a paper derived from it 51 flo s development followed a waterfall lifecycle Unlike the traditional waterfall this one was centered on the production of the user s manual The feedback loops always led into the requirements specification box labeled SPECIFY Thus the manual was worked on in all steps SPECIFY by writing manual i DESIGN features in manual NI CODE features in manual Re TEST against manual Se WD pic WYSIWYG Direct manipulation pic is a WYSIWYG direct manipulation drawing program whose internal representation is the pic language the picture drawing language whose processor is a pre processor in the ditroff family 6 2 WD pic The pic language allows written descriptions of line drawn pictures that are typical in computer science literature For example the pic specification ERS box pic arrow box troff SBE gets translated into ditroff instructions that cause ditroff to display pic a trof
13. they are more easily discarded than design and software 11 Indeed in our case studies no one really complained about throwing out sections of the user s manual per se The complaints if any were When are we going to finish this endless cycle of revisions Can t the d n customer make up his mind However the same complaint would be raised if code were changed as often in order to be able to match the customer s requirements exactly The alternative is to quit early and never match the customer s require ments In fact each of the user s manual authors among this group of paper authors found that throwing out portions of the manual that he or she had written was far less distasteful than throwing out portions of code that he or she had written After all the manual portion is only words but code is code Perhaps this is a phenomenon restricted to programmers as opposed to literature authors but sentences from a manual seem a lot less part of one s person than do lines of code More on the rational side a manual section seems a lot less connected to the rest of the manual than a code section is connected to the rest of the code so it s a lot less disruptive to throw out a manual section than to throw out a code section 17 7 3 3 Ease of Writing Specification as a User s Manual The Nelsons observed that they did not find the process of writing the RS for WD pic difficult because they were not really concentrating on
14. to a false impression of completeness 7 4 5 Validation of Requirements Specifications One key advantage of user s manuals over traditional SRSs is in the ease of validating the requirements docu ment with the customer and users This point was driven home to Berry when he compared use case based user s manual specifications of the enhanced WD pic with a feature centered traditional SRS that had been written by one team for the same Even though he was quite familiar with WD pic from having used a previous version even though he is thoroughly computer literate he had a hard time understanding some specifications of features in the traditional form He could not see that what was specified was not quite what he wanted He had no such problems with any of the user s manual specifications He was able to spot specifications that did not correspond to his desires instantly and to describe what was wrong and how to fix it or at least what the misunderstanding was The clarity of the two specifications were like night and day In fact he even empathized with those customers who report that they understand and accept specifications that they were too embarrassed to admit that they had not understood at all When he thought about it he understood what was the key difference in the two kinds of requirements docu ments The normal SRS describes only what the system being specified does The user s manual describes conversa tions between the user
15. used RSs in the form of use cases agreed to by the customers and the developers Each such use case was described in words and with flowcharts showing the use case s main alternative and exceptional scenarios Each scenario is a tree of menus and choices with voice prompting by the application and telephone key board DTMF input by the user These use cases sufficed as RSs because the applications were in a well understood domain IVR with which users were intimately familiar Over the years principles about IVR user interfaces had been developed and refined to the point that for any given application it was easy to gain a customer s understand ing of any proposed solution without the need to consult each category of users directly This new project with a VUI was in a totally new domain for which there was no user experience In order to gain some experience during the development the company decided to deploy its developing product experimen tally on its own phone system Partly due to market pressures to get the application out early and partly due to the normal use of tacit assumptions the company was following its traditional requirements process producing use cases as RSs Each such use case was again a tree of menus and choices with voice prompting by the application and voice input by the user In other words they were basically the same IVR application use cases with a change of input medium from keyboard to voice These use cases we
16. we have to use many replications of small toy versions of a problem on which the method is applicable However then it is not certain that the conclusions are useful We know that methods that work on toy problems of the size needed for a controlled experiment do not necessarily scale up to industrial sized problems Hence we are left to doing many introspective case studies on applications of the method to industrial sized examples and reporting the lessons learned To be able to measure the success of these case studies i e to show that projects that write user s manuals as requirements specifications finish faster with fewer bugs and a more reliable product it will help if they were car ried out by measuring organizations with track records of successfully predicting resources required for its projects The organizations could compare the actual project data with past experience and the predictions These case studies should be looked at for their lessons learned They can guide anyone who wishes to try the approach out on his or her own development If the reader believes that user s manuals make good requirements specifications he or she should attempt another case study and report what happens 10 Future Work While there is strong support for the conclusions of this paper more work is needed to be able to say definitively that for appropriate CBSs user s manuals make good RSs We need to continue to track the ExpressPath project
17. writing a traditional SRS document Instead they were writing a user s manual which is a familiar document with a well known structure Even more important it is a user centered document which promotes the requirements elicitation process For instance they frequently found themselves asking ques tions like So if the user wants to move an object can he find out how to do it by reading the manual or How will the system respond if the user tries to select a group of objects 7 3 4 For Designers and Implementers It can be argued that a user s manual favors the user over the designer and implementer The user s manual s audience is the user Certainly with a user s manual being use case centered it will be hard for the designer and implementer to identify functions to be implemented A given function may manifest itself in several use cases each giving some different aspects of the functions With only this information the designer or implementer would have to distill the functions out of their many manifestations However a good user s manual has also a feature centered part listing all the individual features and describ ing all of the options of each Indeed this part is organized much as is the typical feature centered traditional SRS The designer and implementer can find the functions already distilled out in this part 7 3 5 User s Manuals Engage Users More than SRSs It is our experience that a user s manu
18. ExpressPath will be setting the standards Consequently difficulty understanding the user s manual raises a con cern regarding the usability of the described system Full details on ExpressPath and the experience specifying it with a user s manual are found in Fainchtein s Master s thesis 16 Fainchtein was a member of the team developing ExpressPath while he was studying for a master s degree in a special program that allowed studying for the degree while still working Fainchtein had just taken Berry s Software Requirements and Specification course for the degree program In this incarnation of the course Berry had assigned as the term project the production of a WD pic specification in the form of a user s manual Fainchtein was searching for an advisor and topic for his master s thesis He approached Berry with the proposal of applying the idea of writing a user s manual as the RS at his job in which he was a developer in the 12 project to build ExpressPath Berry pounced on the idea as a way to get a much needed industrial case study of the proposal of using a user s manual as an RS However Berry was worried that Fainchtein s managers might not be happy about their project with real market driven deadlines being used as a subject in academic research about a technique that is not well known Fortunately the project was in the early stages In previous projects at the company all in the domain of IVR the company had
19. In more than one case the student more than once expressed thoughts that the demanded user s manual was overkill that she was tired of the customer s hardnosed demands that the manual be perfect and that the time was long overdue to move on to coding In the industrial case student there was not going to be a suitable RS and there was not even going to be a totally suitable requirements engineering process Admittedly the project leader was not motivated at first to even try producing a user s manual as the RS It was only when he got an offer that could not be turned down of a user s manual written on an employee s own time with minimal resource demands on employees working for him that he agreed to an attempt to produce a user s manual as the RS for his project Adding to the sweetness of the deal was the realization that a user s manual would eventually have to be written anyway Even in accepting the offer perhaps as a favor to his employee s education that he was already supporting he remained skeptical as to the effectiveness of the user s manual as an RS However once it became apparent to the leader and to the rest of the project team that writing the user s manual was working as predicted as a requirements engineering process and that the were going to get both an acceptable RS and a user s manual for the price of one the entire project team including the leader bought into the user s manual as the spec
20. OK so writing an RS is essential However why is the user s manual more attractive than an RS The user s manual needs eventually to be written anyway for future user s benefit while the RS is likely not to be looked at beyond the beginning of coding Also a user s manual almost always exposes a full set of use cases simply because the manual s purpose is to show how to use the CBS and those use cases can then be used to generate the essential test cases On the other hand an RS written according to at least one of the standards for SRSs 23 tends not to expose a full set of use cases called modes of operation because the SRS s focus is on the functions to be imple mented by the CBS 4 Contents of a Good User s Manual Our own informal examination of a variety of user s manuals leads us to believe that a good user s manual has the following elements 1 descriptions of underlying and fundamental concepts of the CBS 2 a complete graduated set of examples each showing a problem situation the user faces e some possible user responses to the problem in the form of commands to the CBS and the CBS s response to these commands and 3 a systematic summary of all the commands The descriptions of the underlying and fundamental concepts of the CBS constitute a lexicon for the CBS and its requirements 34 The complete graduated set of examples constitutes a defining set of use cases for the CBS 25 Having only t
21. User s Manual as a Requirements Specification Case Studies Daniel M Berry dberry AT uwaterloo DOT ca Khuzaima Daudjee kdaudjee AT uwaterloo DOT ca Jing Dong jdong AT utdallas DOT edu Igor Fainchtein igor_finestein AT Igs DOT com Maria Augusta Nelson guta AT csg DOT uwaterloo ca Torsten Nelson torsten AT csg DOT uwaterloo DOT ca Lihua Ou lizzy_ou AT yahoo DOT com School of Computer Science University of Waterloo Waterloo Ontario N2L 3G1 Canada March 2003 2003 by D M Berry K Daudjee I Fainchtein J Dong M A Nelson T Nelson and L Ou Abstract This paper argues that a user s manual makes an excellent software requirements specification It describes several experiences including one in industry of writing user s manuals as requirements specifications Finally it discusses several lessons learned from the experiences Keywords ambiguity requirements analysis requirements elicitation requirements specification requirements validation requirements scenarios test cases use cases user s manual 1 Introduction The Problem of Writing Good Requirements Specifications There are a number of reasons that writing a requirements specification RS for a computer based system CBS before implementing it is a good idea 12 45 4 46 33 48 36 1 The process of writing the RS of the CBS is a good way to learn the CBS s requirements 2 The process of writing the RS of the CBS helps to reconc
22. al engages the users and customers much more than any more formal requirements specification including the traditional SRS A user s manual is written addressed to the user and gen erally talks to the user An SRS is written addressed to the developer and generally fails to talk to the user 7 4 User s Manuals and Requirements Engineering We found that writing a user s manual forced us to do some RE processes that might otherwise not have been done 7 4 1 Writing User s Manual as an Elicitation and Validation Tool Giving a draft user s manual to the client and to the client s users is a good way to elicit the But I wanted x instead s and the But I wanted x also s before the CBS is implemented i e to validate the requirements The user s manual actually serves a dual purpose 1 aiding the elicitation of correct and complete requirements and 2 being the requirements document 7 4 2 Finding Ambiguities In doing the WD pic project we found that one of the most important benefits of using a user s manual as an RS is that it is easier to find ambiguous RSs In any RS document there may be hidden ambiguities Each such hid den ambiguity gets subconsciously disambiguated one way by each stakeholder e g the user and the implementer who is not even aware that other meanings exist for the sentence 28 The ambiguities are discovered only later when the CBS is delivered and the user discovers that the implemente
23. amples of excluded CBSs are 1 Autonomous systems with no real human users However if a user of the autonomous CBS is another CBS a manual directed at the users of the other CBS might be able to describe all the functionality assumed of the autonomous CBS If the autonomous system reacts to real world phenomena e g tempera ture changes a user s manual written from the perspective of the world e g the weather as a user might be possible 2 A CBS for which one or more algorithms it computes is the major issue of an RS An example of such a CBS is a weather predictor whose core functionality is a particularly effective weather simulator and the algorithm of the simulator is the issue of the RS Other examples are programs to approximate the integral of functions and programs to do life like animations 3 A CBS with significant nontrivial nonfunctional requirements that are not specifically visible to the user e g security reliability and robustness for which the user does nothing to cause the nonfunctional requirement to kick in The particular way that security reliability or robustness is achieved is a major issue for the requirements specification For none of these CBSs would a user s manual serve as a good RS These limitations notwithstanding the approach of taking the user s manual of a CBS as the RS of the CBS is still helpful particularly when the alternative is that no RS would be produced It should be cle
24. and the system to achieve the user s goals Basically the user s manual was more alive 19 Berry could see himself being the user described in the manual and he could thus spot instantly supposed user behavior that did not correspond to what he would do The normal SRS does not describe the user s inputs and reac tions It describes only the system s behavior in a vacuum from the user So Berry had no idea what user behavior was implied Thus if the behavior bore any resemblance to what he thought the system would do to some input of his he was led to believe that the specification was what he wanted 7 5 User s Manuals and Software Engineering Writing a user s manual helps phases of software development other than the RE phase 7 5 1 Scenarios as Test Cases Recall that Wolfman and Berry used the flo ditroff source of the flo manual as the test case for the flo pro gram Of course this benefit came from the lucky accident that flo is a batch program and they wrote the user s manual for flo in the formatting language of the formatting system of which flo is an integral part In a similar fashion Knuth used the TeX source of The TEXbook as the main test case for the TEX program In each case the manual served as the main test case for the formatting software since it describes all the features that are imple mented Such direct use of the manual as a test case is not possible in today s WYSIWYG formatting systems However it
25. ar that the limitations of user s manuals with respect to covering requirements are the same as the limitations of scenarios and use cases 49 They can cover only those requirements that are visible to users However users of scenarios and use cases are quick to point out that even a complete collection of scenarios and use cases do not constitute a RS We have found an approach for dealing with the well understood easily described common nonfunctional requirements typical of user centered CBSs These include such nonfunctional requirements as ease of learning ease of use and performance These can be specified in what we call the bragging section that many user s manu als have A typical such user s manual congratulates the user for having bought a great product with a great user interface and high performance If the sole specification of a nonfunctional requirement is simply its name this name could be mentioned in the bragging section If the specifications are more detailed then other possibilities exist stating what functions provide the easy to learn or easy to use interface in the equivalent of a Q FD deployment of qualities to functions or giving actual performance data e g If you are the only user of the system on which our product is run ning if you are running on a CPU with at least a 50GHz cycle all commands but will respond in less than one second or Our product is capable of editing files of
26. as it completes development ships the software and begins to develop other versions We will need to report on the complete project history including milestone adherence error reports and even whether enthusiasm for the user s manual as the spec is maintained Additional case studies particularly of industrial projects need to be carried out The authors would appreci ate hearing about any project that has carried out or that wishes to carry out user s manual development as its RS Acknowledgements The authors thank the anonymous referees of earlier versions of this paper for incisive demanding com ments Berry was supported in parts by a University of Waterloo Startup Grant and by NSERC grant NSERC RGPIN227055 00 References 1 POSTSCRIPT Language Reference Manual Second Edition Adobe Systems Incorporated Addison Wesley Reading MA 1992 2 Ts it true that Apple User Manual served as Requirements in RE Online ed D Zowghi E mail Mailing List 30 January 2003 22 17 18 19 20 Beizer B Software Testing Techniques International Thomson Computer Press London UK 1990 Second Edition Berry D M and Lawrence B Requirements Engineering IEEE Software 15 2 p 26 29 March 1998 Berry D M What Not How When Is How Really What and Some Thoughts on Quality Require ments Technical Report Computer Science Department University of Waterloo Waterloo
27. bout writing user s manuals both in general and for user s manuals that function as an RS 7 1 1 User s Manual Should Deceive Users The manual should be written well enough that it deceives the reader into believing that the software really exists In fact it s getting the picky details worked out well enough to write the deceptive user s manual that forces ironing out those synergistic problems that plague many requirements and even design documents We have here yet another example of faking it 41 7 1 2 Manuals Should be Written in Present Tense An important rule for writing user s manual and for that matter any RS is to use present tense to talk about what the CBS does notice the present tense in this sentence This rule is certainly consistent with the idea of fak ing it that the CBS is already implemented when writing the user s manual This rule is needed so that when it is necessary to talk about something that happens in the user s future after the user s present in which he says some thing to the CBS future tense can be used to distinguish the future response from the user s present input A typical specifier writes an RS for a not yet implemented product in the future tense After all after the CBS is implemented in the future the user will enter some input and the CBS will do something in response When the RS is written in future tense the specifier has lost the ability to distinguish between the user
28. ect Oriented Software Engineering Addison Wesley Reading MA 1992 John I and Dorr J Elicitation of Requirements from User Documentation in Proceedings of Ninth Inter national Workshop on Requirements Engineering Foundation for Software Quality REFSQ 03 Klagenfurt Velden Austria 16 17 June 2003 Kamsties E H rmann K and 1998 M Schlich Requirements Engineering in Small and Medium Enter prises Requirements Engineering Journal 3 p 84 90 1998 Kamsties E Surfacing Ambiguity in Natural Language Requirements Ph D Dissertation Fachbereich Informatik Universit t Kaiserslautern Germany also Volume 5 of Ph D Theses in Experimental Software Engineering Fraunhofer IRB Verlag Stuttgart Germany 2001 Kauppinen M Kujala S Aaltio T and Lehtola L Introducing Requirements Engineering How to Make a Cultural Change Happen in Practice pp 43 51 in Proceedings of the IEEE Joint International Requirements Engineering Conference RE 02 IEEE Computer Society Press Essen Germany 2002 Kernighan B W PIC A Language for Typesetting Graphics Software Practice Experience 12 p 1 20 January 1982 Kernighan B W A Typesetter independent TROFF Computing Science Technical Report No 97 Bell Laboratories Murray Hill NJ March 1982 Knuth D E The T Xbook Addison Wesley Reading MA 1988 Kotonya G and Sommerville I Requirements Engineering J
29. edge of the requirements can be attributed partially to the readability of the user s manual and partially to the accessibility and concreteness of the prototype Team members other than Fainchtein found it easier than normal to elicit custo mer feedback using the user s manual Fainchtein s participation in the entire requirements analysis and system design including construction of the prototype helped him to produce the user s manual in what felt like a short time period Implementation of some advanced functions and of a major portion of the graphical user interface in the prototype allowed Fainchtein to include screen shots in the manual thus increasing the manual s realism The resulting impression that the system already exists offset some of the understandable difficulties that arose from the fact that the manual was written in advance of the availability of a complete implementation Each portion of the user s manual before being presented to the client had undergone much discussion and modification by the requirements analysis group consisting of Fainchtein another solution developer a solution architect and a domain expert They found that the processes emulated by the prototype system were easier to describe in the user s manual than in the more formal SRS that they eventually wrote The customer also validated these user s manual descriptions faster because he was able to see how certain functions were being used by a u
30. ethod that does not force working out the details is going to work It is only in working out the details that all the show stopping exceptions and interactions are going to be discovered These details can be worked out in any of several media the software itself a complete formal specification a complete traditional SRS or a complete scenario based user s manual The advantage of user s manual over the other media is that changing the manual consistently is much cheaper than changing either the software itself or a complete formal specification Also unlike a complete traditional SRS a user s manual is both needed and perceived as needed after the software is delivered thus the motivation to keep it up to date is higher than that to keep a traditional SRS up to date The advantage of the software itself or a complete formal specification is that it is hard to handwave over the details to cheat to leave the impression of completeness when details are missing If details have been left out the software will not work or the formal specification cannot be verified to satisfy requirements While it is fairly easy to leave details out of a user s manual since the user s manual is intended to be delivered with the software to help naive users the incentive is to get those details in Thus it is an issue of finding a right medium for expressing detailed requirements that is both cheap to change but hard to hand wave one s way
31. f A key point about pic is that every graphical object has a default size e g 75 inches by 5 inches for a box and default position to the right of the previous item Thus many times the user does not have to provide explicit size and position specifications In most WYSIWYG direct manipulation drawing systems after one selects a graphical item in the palette one has to move the mouse over to the canvas in order to specify position and size by clicking twice once at each corner or clicking at one corner and dragging to and unclicking at the other corner In WD pic if everything is of default size and position one should be able to draw a whole picture without ever moving the mouse from the palette To get the figure above one could click the box button click the quote button type p i click the arrow button click the box button click the quote button and aa e OB og Lb SSB SNe 99 66 29 66 gt without ever having to move the mouse out of the palette or even to open up a text window The grammar would tell WD pic that it should expect characters to be entered at the keyboard after the quote button is clicked Of course in pic the user may further qualify a graphic item with size and positioning information There fore in WD pic the user should be able to provide additional size and position information by either clicking some other buttons on the palette editing the i
32. f the game is she l It is difficult to write a good RS one that specifies exactly what the CBS is supposed to do without limiting unnecessarily how to implement it 2 Participants in most projects these days believe that they do not have the time to do so that it is necessary to proceed immediately if not before to coding in order to meet the code s delivery deadline or to be the first in the market with the code s functionality begging the question of how do they know what to imple ment anyway if requirements are not specified 3 Participants in most projects these days perceive that time spent on writing an RS is wasted since the requirements will change anyway and the RS will probably never be read even by the implementers This paper offers the writing of a user s manual for a CBS before implementing it as a method of achieving the writing of an RS of the CBS before implementing it The method both produces a document that delivers the five benefits of writing an RS before implementation and e helps mitigate the three problems that discourage the production of an RS before implementation However the benefits and problem mitigation accrue only for those CBSs for which a user s manual is possible i e the CBS has users and a user s manual that describes essentially all of the CBS s functionality Therefore unless the applicability issue is at hand we assume that the CBS being developed and specified is appropr
33. harts in formal papers Berry even occasionally asked a theoretician at the Technion Nissim Francez for his opinion on features Wolfman the master s student was the SE He was designing and implementing flo as his master s thesis research under Berry s supervision To design and implement flo Wolfman with Berry s feedback wrote an initial user s manual to describe all features that would be implemented They iterated on the initial user s manual until they were satisfied that the specified flo could be used to draw all flowcharts that they had seen in recent books and papers on theory of comput ing and software engineering That is the user s manual became the RS This first version of the user s manual used hand coded pic descriptions to draw each flowchart in the manual to look as if flo had done it These hand coded pic descriptions were also Wolfman s idea of the kind of output that flo would create for the flo input The following steps were carried out simultaneously and repeatedly Wolfman implemented features in flo and commented out hand coded examples in the manual source in order to let the flo generated pic code show through e Wolfman with Berry s feedback modified the manual to reflect changes in flo s implementation that were necessitated by discoveries made during failures to implement features as desired and as described in the manual Wolfman modified the implementation to reflect changes in the
34. hat much to her surprise scenarios not described in the manual but which were nevertheless logical extensions and combinations of those in the manual worked the first time That is the features composed orthogonally without a hitch Berry found Ou s implementation to be production quality and is happily using it in his own work More details on Ou s work can be found in her Master s thesis 40 6 3 ExpressPath an Industrial Case Study The industrial experience involves Igor Fainchtein one of Berry s master s degree students writing a user s manual as an RS for ExpressPath a natural language speech recognition system developed by the LGS Group ExpressPath uses speech recognition to allow software to answer telephones and to satisfy user s requests in a voice interface This voice only interface is more convenient to the user than the traditional labyrinthian menu driven Interactive Voice Response IVR system that uses the telephone s touch tone keyboard for input and that has become the much maligned standard for possibly toll free telephone numbers provided by merchants services and governments Note that as with WD pic s user interface ExpressPath s voice user interface VUD is not well known by the user community Therefore a significant part of the requirements engineering RE effort is the design and structure of the user interface There are no body of experience guidelines and standards upon which to draw
35. hat the RS gets written anyway as one is writing the user s manual and the help system and as one is devising test cases particularly if it is important to deliver a quality CBS product 27 Writing the user s manual requires determining what the CBS does i e its requirements Also in order to test a CBS a full set of test inputs must be determined This determination requires figuring out what the CBS is supposed to do i e the full set of features Then it is necessary to figure out for each test input the expected output This figuring requires determining what the CBS is to do for each test input The complete test plan amounts to an RS of the CBS covering at least the tested features The RS is as complete as the test cases Indeed it is clear that in any CBS development other than for totally private use if the normal minimum required to release and sell the CBS is done there is a budget for testing and writing the manual or help system Therefore there are enough resources for producing an RS These resources include the time for testing and writing the user s manual or help system Therefore it is simply not true that there is not enough time to write the RS Moreover since an error discovered at requirements specification time costs two orders of magnitude less to fix than the same error discovered at delivery time 6 it pays to write the RS test cases and user s manual or help system at the beginning of the project
36. he third loses many readers who do not understand the concepts and turns off many readers who get bored reading page after page after page of command syntax and semantics Leaving out the first makes it very hard for the author to assume and use a consistent vocabulary in writing the rest of the manual Leaving out the second leaves the reader without any sense of what is important and how to use the CBS to solve his problems A well written second part makes reading the manual even the third part fun The third part must be con sulted in order to fully explain why the input of an example solved the problem the example claims it does A good way to organize the first part is around the abstractions that are found in the problem domain Each abstraction that survives the analysis should be explained in terms of 1 what the objects are 2 what they do and 3 what is done to them A good way to organize the second part is around the use cases that have been identified in consultation with the client and the users One can follow any approach to identify use cases 25 49 8 Having identified them it is helpful to decompose them into two groups 1 basic use cases that are used frequently as components of other use cases e g selection of text in a WIMP interface and 2 more complex problem solving use cases e g changing the size and position of a selected box in a picture drawing program The second group can be sorted into a list by
37. iate for offering a user s manual as its specification Accordingly Section 2 shows how a user s manual can serve the five listed purposes of an RS and cites other work that agrees with this claim Section 3 shows how production of a user s manual may help avoid the three problems that inhibit the production of an RS Section 4 describes the structure and contents of a good user s manual and notes that they are the structure and con tents of a good RS Section 5 details the kinds of CBSs for which user s manuals provide good coverage of their requirements and describes how to deal with requirements that are not appropriate for presentation in a user s manual including nonfunctional requirements These sections only argue their points It is necessary to validate these claims in practice Accordingly Section 6 presents four case studies of projects three academic and one industrial in which user s manuals were used as RSs All four involve the production of substantial software applications These cases studies sup port the claims of Sections 2 and 3 Section 7 lists lessons learned in these case studies beyond those that support the claims Section 8 concludes the paper with a discussion of threats to the conclusions and of future work to test the validity of the lessons learned As is shown in Section 2 1 the idea of considering a user s manual an RS is quite old The contribution of this paper is not the idea but
38. ile differences among the CBS s stakeholders 3 The RS allows the customer of the CBS to validate that the projected CBS will be what he wants before resources are spent implementing a possibly incorrect CBS 4 The RS makes it clear what must be implemented to obtain the required CBS 5 The RS allows deriving both covering test cases and expected results that allow verification that the imple mentation of the CBS does what it is supposed to do Despite the clear benefits of writing an RS for a CBS before implementing it many projects are unable to produce the RS for a variety of reasons some technical and some social The focus of building a CBS is on writing the software Hence often we forget that we are dealing with a whole system and talk about developing software Moreover as we give requirements for a CBS we also need to give requirements for the software component in what is known as a software requirement specification SRS In this paper fully cognizant of the necessity to deal with the whole system we often use system and its software interchangeably particularly since the part of the system that is most malleable is the software To avoid the clumsy he or she construction which in turn avoids using plural they for singular everybody any unspecified person on the customer s or user s side of the game is he and any unspecified person on the analyst s or implementer s side o
39. increasing complexity This sorted list can be used as the basis for the graduated set of examples around which to write the user s manual Indeed recently Isabel John and J rg Dorr 26 describe an approach for eliciting requirements for an enhancement of legacy software based on existing user documentation sort of going in the reverse of our direction They too have observed the strong connection between a well written user s manual and use cases Namely the table of contents of such a user s manual is a list of use cases for the legacy system The third part is generally a feature list often in alphabetical order by the feature name The organization and contents of this part are similar to those of a traditional feature centered SRS Thus those e g designers and imple menters who prefer a feature centered RS get it also According to Richard Fairley in his 1985 Software Engineering Concepts 17 a preliminary user s manual should be produced at requirements definition time to get a focused user s view He proposes the following outline for the preliminary as well as the actual manual 1 Introduction Product overview and rationale Terminology and basic features Summary of display and report formats Outline of the manual 2 Getting started Sign on Help mode Sample run 3 Modes of operation Commands Dialogues Reports 4 Advanced features 5 Command syntax and system options Observe tha
40. ion of what the CBS is supposed to do clear enough that the manual s author can visualize scenarios 49 10 of the use of the CBS and describe both 1 what the user should say to the CBS and 2 what the CBS should respond to the user in each of these scenarios Describing this information amounts to describing the use cases of the CBS 21 10 11 because scenarios with steps in common collected into user task focused abstractions are none other than use cases Thus the very process of determining what to say in a user s manual is the same as the process of eliciting requirements to write an RS If a stakeholder says that the user s manual for a CBS describes the desired functionality for the CBS the stakeholder has effectively validated that the CBS described is the CBS the stakeholder desires Moreover when different stakeholders have conflicting requirements these conflicts manifest themselves as differing reactions to portions of the user s manual Discovery of these differing reactions can be followed by negotiations to resolve the conflicts 7 Any time an implementer has a question about the functionality of a CBS she can consult the CBS s user s manual to determine the expected behavior of the CBS just as a user consults the CBS s user s manual to determine both what he can say to the CBS and the CBS s expected response to what he has said An RS is often accompanied by or includes description of scenarios and use
41. lence of RS and user s manuals holds even for these platforms Consider the POSIX system 42 which is a standard generalization of the various UNIX platforms It is specified by a collection of UNIX style manual pages describing the various kernel routines and data that are available to use to write applications running on the platform 1 This collection of manual pages serves as a description of the facilities that an implementation must make available This description gives for each kernel routine the interface it must support 2 This collection of manual pages serves also as a user s manual describing what the programmer of an application may assume about the facilities on which the application is programmed The description gives for each kernel routine the interface that can be assumed by its invoker Any user of any POSIX compliant operating system is supposed to be able to rely on the POSIX specification as a user s manual for the particular operating system Thus even for an operating system a well written user s manual can serve as an RS Of course this style of user s manual aimed at the programmer of applications may not appear well written to the user of such an application 7 2 2 Help Systems as User s Manuals 16 A question that is asked a lot these days when purchasing mass market software is Where have all the manuals gone Software is rarely delivered with a full fledged user s manual covering all functi
42. manual describes the CBS from the user s point of view and not from the implementer s In fact as early as 1975 in The Mythical Man Month 9 Fred Brooks implicitly equated the manual with the written RS for a computer system product by describing the manual s mission as that of an RS The manual must not only describe everything the user does see including all interfaces it must also refrain from describing what the user does not see That is the implementer s business and there his design freedom must be unconstrained The architect must always be prepared to show an implementation for any feature he describes but he must not attempt to dictate the implementa tion Also Tom de Marco suggests in several places using user s manuals as RSs most notably in The Deadline 13 Urban legend has it that the user s manuals for the Lisa and Macintosh computers were written completely before implementation of the software began these manuals were then given to the system programmers as the specification of the appearance and functionality of the user interfaces and hence of the underlying systems 2 2 2 The Five Purposes of a Requirements Specification Achieved by Writing a User s Manual This section argues that the process of writing a user s manual and the resulting user s manual serve the five purposes of writing an RS for a CBS before implementing the CBS Writing a good user s manual for a CBS requires a clear concept
43. mer meet the overall schedule even though writing it caused a schedule slip in the requirements phase and in the case in which there was not going to be a fully documented requirements specification the develop ers have ended up calling the user s manual the requirements However each of these successes in the non industrial cases could have been the result of a bunch of other factors including the abilities of the programmer and the client 21 the client s previous experience with the application the user interface centeredness of the application and the medium size of the application These were not factors in the industrial case In the industrial case the success could have been the result of the Hawthorne effect since writing a user s manual was a totally new and experimental activity for the people involved and the fact that it was at first not considered a real part of the project because it was being done as an academic project on someone s own time Therefore it is not correct to conclude that user s manuals will always make good requirements specifications and that writing the user s manual as the requirements specification will always help a project to be successful There is no completely satisfactory way to validate any software engineering method In order to be able to afford to do a statistically significant controlled experiment validating the effectiveness of any method
44. n Software Inspections IEEE Transactions on Software Engineering SE 12 7 p 744 751 July 1986 Fainchtein I Requirements Specification for a Large Scale Telephony Based Natural Language Speech Recognition System Master s Thesis School of Computer Science University of Waterloo Waterloo ON Canada 2002 Fairley R E Software Engineering Concepts McGraw Hill New York NY 1985 Gause D C and Weinberg G M Exploring Requirements Quality Before Design Dorset House New York NY 1989 Glass R L Can English Majors Write Maintenance Documentation Journal of Systems and Software 21 p 1 2 1993 Gourlay J S A Mathematical Framework for the Investigation of Testing IEEE Transactions on Software Engineering SE 9 6 p 686 709 November 1983 23 21 22 23 25 26 36 37 Hooper J W and Hsia P Scenario Based Prototyping for Requirements Identification SOFTWARE ENGINEERING NOTES 7 5 p 88 93 December 1982 Howden W E Functional Program Testing IEEE Transactions on Software Engineering SE 6 2 p 162 169 March 1980 IEEE IEEE Recommended Practice for Software Requirements Specifications in ANSIIEEE Standard 830 1998 IEEE Computer Society Los Alamitos CA 1998 Anonymous Jackson M A Problem Frames Analysing and Structuring Software Development Problems Addison Wesley Harlow England 2001 Jacobson I Obj
45. n the midst of full time work on and thinking about the system The company s experience with similar sized projects suggests that normally about 5 months would be needed for writing each of an SRS and a user s manual Hence Fainchtein s work represents a significant savings overall They have saved time by writing only one document instead of two Moreover all involved believe that the implementation is going more rapidly and error free than nor mally and they believe that this more rapid development is happening because requirements were clarified and documented in advance of the implementation Thus Fainchtein has gotten one document serving as two for the price of one and he has gotten it early enough to more than pay in reduced development costs for the time he spent in writing the manual During his work on the manual Fainchtein got the usual number of complaints with regard to specified requirements However each of these complaints resulted in a new iteration of the manual and resolution of the problem during requirements analysis time rather than during testing or after delivery Moreover having the RS in the form of a user s manual rather than in the traditional SRS form made it easier for the customer to understand the requirements Consequently the customer s complaints were more specific and more constructive and they often contained a solution In other words the customer knew very well what he wanted The customer s knowl
46. nternal representation or dragging graphical items on the canvas to the desired size and position The first version of WD pic was designed and implemented by Faina Shpilberg one of Berry s master s students at the Technion Shpilberg built her version of WD pic from requirements up with Berry as her customer The main goal of the thesis was to establish the requirements of WD pic by an extended prototyping process similar to that for flo in which the user s manual served as the RS For more details please consult Shpilberg s thesis 44 While the prototyping did establish the basic requirements and did prove the concept Berry was less than happy with the final prototype because a number of features were not quite as desired That they were not right was no fault of Shpilberg Rather the problems were the result of her use of a standard graphical user interface GUI builder that provides a more cumbersome user interface than desired The standard GUI builder used to make pro totyping faster demands clicking an OK button to confirm the correctness of text entered into a text window That such confirmation is unnecessary is indicated by the fact that a user almost never clicks the other non OK button and in the rare case that he would the undo facility could be used to cancel the input Berry vowed that the production version would have its own lighter weight GUI that took advantage of the program s knowledge of pic s grammar to kno
47. ohn Wiley amp Sons West Sussex UK 1998 Leite J C S P and Franco A P M A Strategy for Conceptual Model Acquisition pp 243 246 in Proceedings of the IEEE International Symposium on Requirements Engineering IEEE Computer Society Press San Diego CA January 1993 Leveson N G Intent Specification An Approach to Building Human Centered Specification in Proceed ings of the Third IEEE International Conference on Requirements Engineering IEEE Computer Society Press Colorado Springs CO 1998 Nuseibeh B and Easterbrook S Requirements Engineering A Roadmap in The Future of Software Engineering 2000 ed A Finkelstein ACM Limerick Ireland June 2000 Nuseibeh B A Weaving the Software Development Process Between Requirements and Architecture in Proceedings of the ICSE2001 Workshop From Software Requirements to Architectures STRAW O1 24 38 39 40 43 Toronto ON Canada May 2001 Nuseibeh B A Weaving Together Requirements and Architecture IEEE Computer 34 3 p 115 117 March 2001 Ossana J F NROFF TROFF User s Manual Technical Report Bell Laboratories Murray Hill NJ October 11 1976 Ou L WD pic a New Paradigm of Picture Drawing Programs and its Development as a Case Study of the Use of its User s Manual as its Specification Master s Thesis School of Computer Science University of Waterloo Waterloo ON Canada 2002
48. on of WD pic The actual project history was a bit different with Ou spending a lot more time than planned in requirements specification Duration in months Step 1 Preparation 4 9 Writing of user s manual requirements specification 11 versions 7 Design including planning implementation strategy for maximum reuse of pic code and JAVA library 1 7 Implementation including module testing and 3 manual revisions 1 7 Integration testing including 1 manual revision and implementation changes 10 Total actual While the detailed plan was not followed the total project time was as planned Moreover Ou ended up pro ducing two implementations for the price of one the planned one for the Sun with UNrx and another for the PC with Windows 2000 That Ou finished on time was more of a surprise to her than to her advisor Berry who had a lot of faith in the power of good requirements engineering to reduce implementation effort Adding to Ou s surprise was that the requirements phase took nearly 5 months instead of the planned 2 months In her view the schedule 11 had slipped 3 months out of 10 way beyond recovery In Ou s past experience as reflected by her long projected implementation and testing times and the 1 month buffer implementation is normally slowed by the discovery of new requirements that necessitate major rewriting and restructuring This time however thanks to the completeness of the RS
49. onality Instead a manual covering only installation and initial start up is provided and the installed software comes with a help sys tem The help system replaces the full fledged user s manual in describing all the implemented functions from the user s point of view The help system is organized around use cases and scenarios Indeed the table of contents of the help system is basically a list of use cases Each selected page gives one or more scenarios for the use case A properly constructed help system provides the same information as a properly constructed user s manual Therefore we believe that constructing a help system should be just as effective for determining and specifying requirements as writing a user s manual 7 3 Why User s Manuals Work as Requirements Specifications On several occasions we put our fingers on explanations for why user s manuals make good RSs 7 3 1 Exposing Intent and Prototyping Our experiences with writing and refining the WD pic User s Manual show that the user s manual is a good representation of WD pic s requirements The user s manual describes more than the requirements i e it captures the requirements of WD pic while also providing the user with step by step instructions of how to use the features of WD pic This description amounts to a statement of intent 35 43 Understanding this intent is critical for the implementers who may not have access to the specifiers When the implementer
50. r did not implement what she understood of the RS In our experience in the production of several user s manual specifications of WD pic the students clarified a number of misunderstandings with Berry by showing him a UI and a number of use cases His reactions to the UI and the use cases made the ambiguities and his intent clear and helped to disambiguate the ambiguities 18 7 4 3 Finding Unexpected Implications Very often unexpected interactions between requirements are not found until the code is written or even until the CBS is deployed We have found the process of writing and validating a manual effective in helping the require ments engineer to find these interactions earlier than they might otherwise be particularly if scenarios exercising the requirements are described in the manual An example is the use of a grid in WD pic When the Nelsons tried to explain to the user how to use a grid to position objects they noticed that enabling a grid would affect the behavior of other features in the system Although the grid was one of the initial requirements the interaction with other features and subsequent effect on their behavior was noticed only when writing the user s manual The Nelsons then had to study the other features and revise their manual to reflect the feature interactions Daudjee experienced the same phenomenon in the writing of his user s manual 7 4 4 Details Tradeoff and No Handwaving No requirements specification m
51. re being accepted without reconsidering the tacit assump tions and without consulting any category of users except the developers who were the users of the in house experi mental deployment Occasionally these user developers were prototyping particularly troublesome scenarios but again without consulting any category of users but themselves Fainchtein realized since the VUI was entirely new technology less familiar to the customers and developers it was necessary to revise the requirements process It was necessary to institute a requirements process involving all categories of the users and much more often rethinking the application from the ground up questioning tacit assumptions exploring entirely different alternatives and producing an RS that described the application thoroughly eS The goal of describing the application thoroughly would force consideration of all the details and questioning of tacit assumptions Fainchtein believed that writing a user s manual as an RS would be a good method to do what was needed and to get the desired RS Fainchtein approached the project leader with the idea to produce an RS in the form of a user s manual This idea did not appeal to the manager since he had never taken this approach before and therefore he perceived the technical risk to be too great However he understood that 1 some RS would be useful even though he did not perceive that he had the resources for it or that it wa
52. rted Once implementation started when not if new requirements were discovered the manual should be modified to capture the new requirements so that in the end the manual described the program as delivered The customer was determined to have a specially handcrafted GUI taking advantage of the program s knowledge of the current state of parsing its input from the user so that there would be no need for confirming with a mouse click the acceptability of what he just finished typing at the keyboard It should be mentioned that prior to entering graduate school Ou had built other systems in industrial jobs mainly in commerce In these jobs she had followed the traditional waterfall model with its traditional heavy weight SRS and had made effective use of libraries to simplify development of applications After accepting the project as her thesis topic Ou wrote a project plan that reflected her waterfall model experience Duration inmonths Step 1 Preparation 2 Requirements specification 4 Implementation 2 Testing 1 Buffer probably more implementation and testing 10 Total planned The first month preparation consisted in learning pic and studying and playing with Shpilberg s prototype and studying the RSs written by Daudjee Dong and the Nelsons Based on this information and input from Berry Ou was to scope the project to a coherent set of requirements for a first production quality versi
53. s valuable enough to commit his precious resources to it and 2 eventually a user s manual would need to be written Fainchtein offered to write the user s manual on his own time the company was already supporting his studies for the master s degree and had already set aside some of his time for his studies The project leader agreed that Fain chtein would write a user s manual on a part time basis during time allotted to his studies but he could interact with project personnel and other stakeholders freely Thus the manager got a needed document at a cost reduced to well below the document s perceived necessity at a considerably reduced technical risk and with a very high potential payoff in reduced costs errors etc Note that the user s manual was being written while rapid prototyping was being used to identify require ments Thus the user s manual was not functioning as a poor man s prototype it was serving merely as an RS 13 However the user s manual did make prototyping of some ideas unnecessary Once an initial prototype had esta blished a particular paradigm in users minds variations described in the form of scenarios in trial manual sections were clear and concrete enough to allow selection of the best variation without having to actually implement them in a prototype for presentation to the users for trial Production of the user s manual as an RS required 5 5 months of part time work by Fainchtein i
54. s have a question about the mean ing of the RS in the absence of access to the specifiers knowledge of the intent helps the implementers to figure out the intended meaning The process of improving the user s manual is iterative and can serve to incorporate new features into the CBS through iterative development It is not an accident that iterative development of a user s manual parallels the iterative development process of software systems Since the user s manual allows the user to imagine interacting with the CBS it serves to provide feedback on whether the CBS incorporates the required features of the CBS In addition it also allows the developers to gather new requirements for the CBS In this con text the user s manual can be considered to be a poor man s prototype and the writing and improvement of the user s manual is a rapid prototyping process This form of rapid prototyping is an inexpensive process Little or no code has to be written and no com plete running product has to be developed At most a few screen mockups have to be written to create illustrations for the manual It is a poor man s prototype The resulting user s manual serves as a cost effective and low cost framework and knowledge base for the later development 7 3 2 Scenarios for Requirements Use cases and scenarios are a good way to represent the user s requirements 29 Because use cases and scenarios are more malleable than design or software
55. ser The customer went so far as to say that presenting the RS to him in the form of a user s manual as opposed to a trad itional SRS contributed to a reduction in the overall time spent by his representatives to validate the requirements and allowed him to involve more domain experts and those who had no previous experience dealing with a tradi tional heavy SRS As confirmed by the originally skeptical project manager prototyping and the user s manual allowed require ments analysis group to detect in the first iteration more than 75 of all problems that they have found in the imple mentation These problems were fixed immediately and the fixes were reflected in the next versions of the prototype and the user s manual More generally the manager observed that the manual was a source of test cases for the quality assurance personnel He noted also that the customer expressed satisfaction with the fact that the require ments processes allowed the customer and the developers to detect and readily address any human computer interaction problem that arose during requirements specification In each case an actual metric is compared with an expected metric the expected metric is based on the company s past history with projects of similar size and complexity There is no way of knowing exactly what the other way would have cost short of doing the project twice and no one is going to do that with carefully selected skill balanced groups
56. t Chapters 2 and 3 about Getting Started and Modes of Operation are precisely a list of scenarios dressed up as a list of problems with which the user might be faced and how to solve them with the CBS being described The chapter about Getting Started can show the entire scenario of a sign on to the application and a use of the application to solve a single representative problem It can then give the basic use cases that are used in other use cases that are the subject of the chapter about Modes of Operation This latter chapter can consist of the gra duated set of use cases that involve using most if not all features 5 CBSs Admitting User s Manuals as RSs The approach of offering a user s manual as the principal or only RS of a CBS works only for those CBSs for which a user s manual describes all but trivially explained requirements Thus the CBS being specified must have the following properties 1 The CBS must have at least one kind of user 2 The CBS must provide all but trivially explained functionality through at least one user interface and all of this functionality must be well understood from descriptions of the behavior seen by a user 3 Each of the CBS s nonfunctional requirements must be well understood and easily described in prose If a CBS has several kinds of users one user s manual can be written for each kind However then achieving and maintaining consistency of all user s manuals becomes a problem Ex
57. the CBS in terms of solutions and treat a specific solution as a general requirement They produce RSs specifying many implementation details These details are mixed in with general requirements that are offered as rationale motivating the solutions disguised as requirements On the other hand writing a good user s manual for a CBS forces focusing on the user s view of the CBS With the typical user in mind as the future audience of the user s manual it becomes easier to focus on the user s view the what of the CBS and to avoid burdening the user with implementation details Even if a requirements writer should lapse into writing about some implementation details a test audience of future users will surely com plain about these extraneous digressions into implementation details Thus while a user s manual is ostensibly different from an RS they in fact convey the same information and a good user s manual should be easier to write than a good RS The other inhibitions against writing an RS for a CBS are that 1 in many organizations the perception is that there is not enough time to write the RS it is necessary to get on to the coding as quickly as possible and 2 many view writing an RS as unnecessary as a waste of time After all the requirements will change as the program is being written and the RS will not be kept up to date therefore why bother One possible way to motivate writing an RS is to foster a realization t
58. the validation of the idea The contribution of this paper is its descriptions of the details of several developments of non trivial CBSs developments in which the user s manual played the role of the RS These case studies allow evaluation of the effectiveness and the payoff of the approach Demonstrated effectiveness and payoff can help provide the motivation that overcomes the inhibitions against writing an RS early in a CBS s development 2 User s Manuals as Requirements Specifications This section argues that for an appropriate CBS a good user s manual has most of the information that is needed in an RS that focuses on the what as opposed to the how of the described CBS Therefore a good user s manual can satisfy the five listed purposes of an RS 2 1 Information in a User s Manual A bit of thought reveals that the information that is in a properly written user s manual for a CBS is precisely what should be in an RS of the CBS We are told that the RS should describe what the CBS does and not how the CBS does it 18 24 5 We are told that the RS should describe the CBS s function and not the CBS s implementa tion We are told that the RS should describe the CBS from the user s point of view and not the implementer s A good user s manual for a CBS describes what the CBS does and not how the CBS does it A good user s manual for a CBS describes the CBS s function and not the CBS s implementation A good user s
59. ures to put in the manual This prototype helps also to get the client to validate the requirements 7 1 5 Skills Needed to Write a Good User s Manual Writing a good user s manual takes skill and there is no substitute for that skill In an industrial situation the client and the CBS producer must hire good writers to write good conception and requirements documents The skills to write a good RS include general writing skills These skills may be more important than that of understand ing the CBS to be built Bob Glass reports how non software knowledgeable English majors were successful in writing high quality descriptions of the grubby details of programs in documentation about these programs for maintainers 19 7 2 Special Kinds of User s Manuals Sometimes user s manuals are written for users of a system other than the ordinary user of an application An example mentioned in Section 2 2 is the system maintainer user There are yet others Also a help system should be an acceptable substitute for a user s manual as an RS 7 2 1 Requirements and User s Manuals for Platforms A computing platform such as an operating system is one kind of software that has a special class of users that differs considerably from the class of users for a single application The user of such a platform tends to be a sophisticated user who programs applications for use by others These applications are programmed to run on the platform The equiva
60. ving test cases from the scenarios in the user s manual Users are strongly influenced by the user s manual and tend to adopt the modus operandi implicit in the way the scenarios choose to solve problems To the extent that the scenarios are representative of the ways that the users will use the CBS scenario generated test cases will tend to cover the probable usage patterns better than arbitrarily generated test cases 8 Conclusions Writing a good RS is hard and it is hard to motivate people to write one A user s manual is an ideal RS in many cases because if it is well written it is written at the level of what the user sees it describes the basic concepts and it does not describe implementation details That is it is written at the right level of abstraction for an RS Isn t that how all bugs show up 20 Certainly all the case studies have demonstrated that for appropriate CBSs the production of a user s manual and the user s manual itself serve the purposes of and provide the benefits of producing an RS and the RS itself However the issue of whether producing a user s manual helps mitigate the inhibitions against producing an RS remains In the academic case studies there were few inhibitions to producing an RS even in the form of a user s manual because the customer demanded it and the developers knew that they would not get their master s degrees unless they met their customer s demands
61. w when text begins and ends thus making the use of a text window totally unnecessary After Shpilberg finished her thesis Berry thought it was time to try to get an improved version going Conse quently in a graduate seminar on requirements engineering taught by Berry at the University of Waterloo four of the students that are the other authors of this paper carried out a project on improving the first version of the WD pic manual They produced three different manuals two by one person teams Daudjee and Dong and one by a two person team the Nelsons The objective of the project was to determine if the user interface UI of WD pic could be redesigned to improve user interaction with the features of the CBS The RSs produced by Dong Daudjee and the Nelsons were never implemented These RSs were produced as the term project of a single semester requirements engineering seminar and there was no follow on course to imple ment the specified CBSs About a year later Lihua Ou approached Berry about doing a Master s thesis under his supervision She chose from among several possible projects the RS and implementation of the first production quality WD pic for the customer Berry 10 Ou was to write the RS of WD pic in the form of a user s manual This user s manual was 1 to describe all features as desired by the customer and 2 to be accepted as complete by the customer before any work on the design or implementation was sta
62. xperience writ ing a user s manual as an RS for an industrial product as part of the research for his master s thesis under Berry s supervision 6 1 flo In 1988 Berry assisted in the writing of a user s manual as a primary requirements document This experi ence had an interesting twist to it that cannot happen for all software however it is interesting from the total software engineering perspective The program was flo 51 which is a pic 30 preprocessor which in turn is a ditroff device independent troff 39 31 preprocessor flo s purpose is to translate a flowchart specification which is embedded inside a file containing ditroff input into a pic specification which in turn is translated by the pic pro gram into more ditroff input The flowchart specification is a textual algorithm in a Pascal like notation The gen erated pic specification describes the flowchart as a picture and the generated ditroff input draws the individual shapes of the picture The specified flowchart is constrained to be no larger than a single page because the output of the ditroff program is a sequence of programs in a page description language such as POSTSCRIPT 1 Each such program prints a single page of the typeset document There were two roles in the development of flo the client and the software engineer SE Berry the advisor was the client an occasional writer of computer science theory papers representing all people who use flowc

User's Manual as a Requirements Specification: Case Studies

Contents

Download Pdf Manuals

Related Search

Related Contents