Within requirements engineering it is generally accepted that in writing specifications (or indeed any requirements phase document), one attempts to produce an artefact which will be simple to comprehend for the user. That is, whether the document is intended for customers to validate requirements, or engineers to understand what the design must deliver, comprehension is an important goal for the author. Indeed, advice on producing 'readable' or 'understandable' documents is often included in courses on requirements engineering. However, few researchers, particularly within the software engineering domain, have attempted either to define or to understand the nature of comprehension and it's implications for guidance on the production of quality requirements.Therefore, this paper examines thoroughly the nature of textual comprehension, drawing heavily from research in discourse process, and suggests some implications for requirements (and other) software documentation. In essence, we find that the guidance on writing requirements, often prevalent within software engineering, may be based upon assumptions which are an oversimplification of the nature of comprehension. Hence, the paper examines guidelines which have been proposed, in this case for use case descriptions, and the extent to which they agree with discourse process theory; before suggesting refinements to the guidelines which attempt to utilise lessons learned from our richer understanding of the underlying discourse process theory. For example, we suggest subtly different sets of writing guidelines for the different tasks of requirements, specification and design.
Keywords:Requirements, Comprehension, Discourse Process, Use Case, Specification, UML
Introduction: The importance of comprehensionThe complete, accurate and concise documenting of requirements is of vital, perhaps paramount importance (Glass 1998) within software development, and errors made in this phase are often considered the most difficult to solve and most costly to fix (Bray 2002). Hence, the potential benefits of successful comprehension (Graesser et al. 1994), promise improvements in software quality, stakeholder satisfaction and development costs. However, comprehension is 'a complex interaction of basic cognitive processes ) which can be regarded as 'one of the most complex and uniquely human of cognitive activities' , and thus, understanding the nature of comprehension is far from trivial.One area which offers a valid means of investigating comprehension is that of Discourse Process. Bamberg and Moissinac (2003) define discourse as 'broadly taken to mean the use of language beyond that of a single sentence'. Discourse Process analyses the way in which sequences of sentences combine to produce coherent sections of language; and thus extends the traditional linguistic study of the construction of individual sentences (Crystal 1997;Graesser et al. 1997).Requirements techniques aim to communicate sets of concepts and meanings which have been constructed, often within sizeable...