Skip to main content
SpringerLink
Log in

User’s manual as a requirements specification: case studies

  • Original Article
  • Published:
Requirements Engineering Aims and scope Submit manuscript

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.

This is a preview of subscription content, log in via an institution to check access.

Access this article

Log in via an institution

Price excludes VAT (USA)
Tax calculation will be finalised during checkout.

Instant access to the full article PDF.

Institutional subscriptions

Fig. 1
Fig. 2

Similar content being viewed by others

Notes

  1. 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.

  2. 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 of the game is “she”.

  3. 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”.

  4. 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.

  5. Isn’t that how all bugs show up?!?

References

  1. Adobe Systems Inc (1992) PostScript language reference manual, 2nd edn. Addison Wesley, Reading, MA

  2. Anonymous (2003) Is it true that Apple User Manual served as requirements? D. Zowghi (ed) RE-Online e-mail mailing list, 30 January 2003

  3. Beizer B (1990) Software testing techniques, 2nd edn. International Thomson Computer Press, London

  4. Berry DM, Lawrence B (1998) Requirements engineering. IEEE Software 15:26–29

    Article  Google Scholar 

  5. Berry DM (2001) What, not how? When is ‘how’ really ‘what’? and some thoughts on quality requirements. Technical report, Computer Science Department, University of Waterloo, Canada

  6. Boehm BW (1981) Software engineering economics. Prentice-Hall, Englewood Cliffs, NJ

  7. Boehm BW, Ross R (1989) Theory W software project management: principles and examples. IEEE Trans Software Eng SE-15:902–916

    Google Scholar 

  8. Breitman KK (2000) Evolução de cenários (Scenario evolution). Dissertation, Departamento de Informática, Pontifícia Universidade Católica, Rio de Janeiro, Brazil

  9. Brooks FP Jr (1975) The mythical man-month: essays on software engineering. Addison Wesley, Reading, MA

  10. Carroll J, Rosson MB, Chin G, Koenemann J (1998) Requirements development in scenario-based design. IEEE Trans Software Eng SE-24:1156–1170

    Google Scholar 

  11. Carroll JM (2002) Scenarios and design cognition. In: Proc IEEE joint international requirements engineering conference (RE’02), Essen, Germany, IEEE Computer Society, Los Alamitos, CA, pp 3–5

  12. Davis AM (1990) Software requirements: analysis and specification. Prentice-Hall, Englewood Cliffs, NJ

    Google Scholar 

  13. DeMarco T (1997) The deadline. Dorset House, New York

  14. Dörr J, Kerkow D, von Knethen A, Paech B (2003) Eliciting efficiency requirements with use cases. In: Proc ninth international workshop on requirements engineering: foundation for software quality (REFSQ’03), Klagenfurt/Velden, Austria 16–17 June 2003

  15. Fagan ME (1986) Advances in software inspections. IEEE Trans Software Eng SE-12:744–751

    Google Scholar 

  16. Fainchtein I (2002) Requirements specification for a large-scale telephony-based natural language speech recognition system. Thesis, School of Computer Science, University of Waterloo, Canada

  17. Fairley RE (1985) Software engineering concepts. McGraw-Hill, New York

  18. Gause DC, Weinberg GM (1989) Exploring requirements: quality before design. Dorset House, New York

    Google Scholar 

  19. Glass RL (1993) Can English majors write maintenance documentation?. J Syst Software 21:1–2

    Article  Google Scholar 

  20. Gourlay JS (1983) A mathematical framework for the investigation of testing. IEEE Trans Software Eng SE-9:686–709

    Google Scholar 

  21. Hooper JW, Hsia P (1982) Scenario-based prototyping for requirements identification. Special Issue on Rapid Prototyping, working papers from the ACM SIGSOFT Rapid Prototyping Workshop. Software Eng Notes 7:5, 88–93

    Google Scholar 

  22. Howden WE (1980) Functional program testing. IEEE Trans Software Eng SE-6:162–169

    Google Scholar 

  23. IEEE (1998) IEEE recommended practice for software requirements specifications, ANSI/IEEE Standard 830-1998. IEEE Computer Society, Los Alamitos, CA

  24. Jackson MA (2001) Problem frames: analysing and structuring software development problems. Addison-Wesley, Harlow, England

    Google Scholar 

  25. Jacobson I (1992) Object-oriented software engineering. Addison Wesley, Reading, MA

  26. John I, Dörr J (2003) Elicitation of requirements from user documentation. In: Proc ninth international workshop on requirements engineering: foundation for software quality (REFSQ’03), Klagenfurt/Velden, Austria, 16–17 June 2003

  27. Kamsties E, Hörmann K, Schlich M (1998) Requirements engineering in small and medium enterprises. Requirements Eng J 3:84–90

    Google Scholar 

  28. Kamsties E (2001) Surfacing ambiguity in natural language requirements. Dissertation, Fachbereich Informatik, Universität Kaiserslautern, Germany, also volume 5 of PhD theses in Experimental Software Engineering, Fraunhofer IRB, Stuttgart

  29. Kauppinen M, Kujala S, Aaltio T, Lehtola L (2002) Introducing requirements engineering: how to make a cultural change happen in practice. In: Proc IEEE joint international requirements engineering conference (RE’02), Essen, Germany, IEEE Computer Society, Los Alamitos, CA, pp 43–51

  30. Kernighan BW (1982) PIC—a language for typesetting graphics. Software Pract Exp 12:1–20

    Google Scholar 

  31. Kernighan BW (1982) A typesetter-independent TROFF. Computing science technical report no. 97, Bell Laboratories, Murray Hill, NJ, March 1982

  32. Knuth DE (1988) The TEXbook. Addison Wesley, Reading, MA

  33. Kotonya G, Sommerville I (1998) Requirements engineering. Wiley, West Sussex, UK

  34. Leite JCSP, Franco APM (1993) A strategy for conceptual model acquisition. In: Proc IEEE international symposium on requirements engineering, San Diego, January 1993, IEEE Computer Society, Los Alamitos, CA, pp 243–246

  35. Leveson NG (1998) Intent specification: an approach to building human-centered specification. In: Proc third IEEE international conference on requirements engineering, Colorado Springs, CO, IEEE Computer Society, Los Alamitos, CA

  36. Nuseibeh B, Easterbrook S (2000) Requirements engineering: a roadmap. In: Finkelstein A (ed) The future of software engineering. ACM, Limerick, Ireland

  37. Nuseibeh BA (2001) Weaving the software development process between requirements and architecture. In: Proc ICSE2001 Workshop: From software requirements to architectures (STRAW-01), Toronto, May 2001

  38. Nuseibeh BA (2001) Weaving together requirements and architecture. IEEE Comp 34:115–117

    Article  Google Scholar 

  39. Ossana, J.F (1976) NROFF/TROFF user’s manual. Technical report, Bell Laboratories, Murray Hill, NJ, 11 October 1976

  40. Ou L (2002) 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. Thesis, School of Computer Science, University of Waterloo, Canada

  41. Parnas DL, Clements PC (1986) A rational design process: how and why to fake it. IEEE Trans Software Eng SE-12:196–257

    Google Scholar 

  42. IEEE (1988) POSIX, IEEE Standard portable operating system interface for computer environments, Technical Committee on Operating Systems of the IEEE Computer Society, IEEE Standard 1003.1-1988

  43. Ravid A (1999) A method for extracting and stating software requirements that a user interface prototype contains. Thesis, Faculty of Computer Science, Technion, Haifa, Israelftp://www.cs.technion.ac.il/pub/misc/dberry/alon.ravid/Thesis.doc

  44. Shpilberg F (1997) WD-pic, A WYSIWYG, direct-manipulation pic. Thesis, Faculty of Computer Science, Technion, Haifa, Israel

  45. Siddiqi J, Shekaran MC (1996) Requirements engineering: the emerging wisdom. IEEE Software 9:15–19

    Google Scholar 

  46. Sommerville I, Sawyer P (1997) Requirements engineering, a good practice guide. Wiley, Chichester, UK

  47. Swartout W, Balzer R (1982) The inevitable intertwining of specification and implementation. Comm ACM 25:438–440

    Article  Google Scholar 

  48. van Lamsweerde A (2000) Requirements engineering in the year 00: a research perspective. In: Proc 22nd international conference on software engineering, Limerick, Ireland, ACM, New York

  49. Weidenhaupt K, Pohl K, Jarke M, Haumer P (1998) Scenarios in system development: current practice. IEEE Software 15:34–45

    Article  Google Scholar 

  50. Wolfman T (1989) flo—A language for typesetting flowcharts. Thesis, Faculty of Computer Science, Technion, Haifa, Israel

  51. Wolfman T, Berry DM (1990) flo—A language for typesetting flowcharts. In: Furuta R (ed) Electronic publishing ‘90. Cambridge University Press, Cambridge, pp 93–108

Download references

Acknowledgements

The authors thank the anonymous referees of earlier versions of this paper for incisive, demanding comments. Berry was supported in parts by a University of Waterloo Startup Grant and by NSERC grant NSERC-RGPIN227055-00.

Author information

Authors and Affiliations

  1. School of Computer Science, University of Waterloo, Waterloo, Ontario, N2L 3G1, Canada

    D. M. Berry, K. Daudjee, J. Dong, I. Fainchtein, M. A. Nelson, T. Nelson & L. Ou

Authors
  1. D. M. Berry
    View author publications

    You can also search for this author in PubMed Google Scholar

  2. K. Daudjee
    View author publications

    You can also search for this author in PubMed Google Scholar

  3. J. Dong
    View author publications

    You can also search for this author in PubMed Google Scholar

  4. I. Fainchtein
    View author publications

    You can also search for this author in PubMed Google Scholar

  5. M. A. Nelson
    View author publications

    You can also search for this author in PubMed Google Scholar

  6. T. Nelson
    View author publications

    You can also search for this author in PubMed Google Scholar

  7. L. Ou
    View author publications

    You can also search for this author in PubMed Google Scholar

Corresponding author

Correspondence to D. M. Berry.

Rights and permissions

Reprints and permissions

About this article

Cite this article

Berry, D.M., Daudjee, K., Dong, J. et al. User’s manual as a requirements specification: case studies. Requirements Eng 9, 67–82 (2004). https://doi.org/10.1007/s00766-003-0181-1

Download citation

  • Received:

  • Accepted:

  • Published:

  • Issue Date:

  • DOI: https://doi.org/10.1007/s00766-003-0181-1

Keywords

Search

Navigation