Linguistic Patterns, Styles, and Guidelines for Writing Requirements Specifications: Focus on Use Cases and Scenarios

A system requirements specification is a technical document extensively used during the respective system life cycle. It gathers the concerns and needs of various stakeholders, describes the common vision of that system, and therefore supports its development and operation processes. The popular form to write requirements specifications is with natural languages that, however, exhibit characteristics that often introduce quality problems, such as inconsistency, incompleteness, and vagueness, which shall be mitigated or avoided to some extent. This paper is part of a series of papers that have discussed linguistic patterns and linguistic styles to produce technical documentation more systematically and consistently. Specifically, this paper proposes a cohesive set of patterns and styles to better write use cases and scenarios. It also presents 38 practical guidelines and supports the discussion with concrete pedagogical examples represented with different styles, namely: visual use cases diagram (UML), a rigorous requirements specification language (RSL), and two informal controlled natural languages, one with a compact (CNL-A) and another with a more complete and verbose writing style (CNL-B). We conducted a pilot evaluation session with 24 subjects who provided encouraging feedback, with positive scores in all the analyzed dimensions. Based on this feedback, we may conclude that the adoption of these patterns, styles, and guidelines would help to produce better requirements specifications, written more systematically and consistently.