1 of 47

SPECIFYING WITH NATURAL LANGUAGE

How can we specify requirements with natural language effectively?

Lecture 8

Some slides in this lecture adapted from https://www.ifi.uzh.ch/en/rerg/courses/hs23/re-i.html

2 of 47

Announcements

  • HW3 Peer Eval (optional) closes tonight 11:59pm
  • Mid-quarter evaluative feedback survey due tomorrow 11:59pm
  • Next Thursday’s lecture (5/9) will be pre-recorded and posted
    • No in-person lecture that day

Text questions to (562) 684-8307

2

3 of 47

Canvas Quiz

​

​

​

Lecture 8: Lecture 7 Review

Text questions to (562) 684-8307

3

4 of 47

Last Time – How do we document what the SW should do?

  • Requirements are documented in various work products: sentences, user stories, graphic models, specification documents, product backlogs, sketches, prototypes, and more
    • Choice of work products used is dependent on the situation
    • Range from informal to formal
  • Glossaries are crucial for promoting shared understanding
  • In all RE situations, functionality, quality, constraints, and context/boundary must be documented
  • Correctness and understandability are key qualities when documenting requirements
    • Followed closely by verifiability and consistency

​

Text questions to (562) 684-8307

4

5 of 47

Text questions to (562) 684-8307

5

Source: “Requirements Engineering for Software and Systems” by Phillip A. LaPlante, p. 95

6 of 47

Free documentation in �unrestricted natural language (NL)

  • Unlimited expressiveness, communicability, understandability, changeability, easier error detection (sometimes)
  • but prone to many of the specification errors & flaws (ambiguities, misinterpretation, incompleteness, contradictions, unverifiable)

Text questions to (562) 684-8307

7 of 47

Today’s Lecture – How can we specify requirements with natural language effectively?

  • Natural language tips
  • Templates
  • User stories

7

8 of 47

Today’s Lecture – How can we specify requirements with natural language effectively?

  • Natural language tips
  • Templates
  • User stories

8

9 of 47

RE Natural Language Tips

  • Use shall/will/should carefully
  • Avoid imprecise terminology
  • Make it measurable!

Text questions to (562) 684-8307

10 of 47

Use shall/will/should carefully

  • Shall: specifies a feature or function that is required in the product and which the product development team must provide.
    • REQUIREMENT
  • Will: predicts the existence of a feature or function in the product/system, but does not identify who is responsible for developing it.
    • ASSUMPTION
  • Should: specifies a desired or optional feature or function of the product. The product development team can choose not to implement the feature or function and still develop an acceptable product.
    • CONSTRAINT or SUGGESTION
    • Often not appropriate to use in an SRS

11 of 47

Examples

  • Shall – “The maximum speed of the treadmill shall be 10 mph.”
  • Will – “The treadmill will be serviced monthly by a certified technician.”
  • Should – “The treadmill speed should not exceed 10 mph.”

Text questions to (562) 684-8307

12 of 47

Avoid Imprecise Terminology

Text questions to (562) 684-8307

  • etc.
  • and so on
  • among others
  • any
  • several
  • various
  • and/or
  • not limited to
  • as well as
  • or
  • state of the art
  • user-friendly
  • safe
  • reliable
  • robust
  • adequate
  • acceptable
  • normal
  • proper
  • reasonable
  • easy
  • simple
  • rapid
  • appropriate
  • suitable
  • possible
  • average
  • timely
  • typical
  • secure
  • optimum
  • efficient
  • improved
  • optimal
  • sufficient

13 of 47

Verifiability: usability example

  • The system should be easy to use by experienced controllers and should be organized in such a way that user errors are minimized.

​

​

13

14 of 47

Verifiability: usability example

  • The system should be easy to use by experienced controllers and should be organized in such a way that user errors are minimized.

​

​

  • The system shall be useable by experienced controllers. The average number of errors made by experienced controllers should not exceed two per day.�Users are considered experienced controllers after a total of two hours training.

14

15 of 47

Make it Measurable!

Text questions to (562) 684-8307

Source Sommerville, 2004

16 of 47

Canvas Quiz

​

​

​

Lecture 8: Poorly-written Requirements

Text questions to (562) 684-8307

16

17 of 47

More natural language tips

  • Construct glossaries
  • Construct a data dictionary
  • Use stylistic rules
  • Attach a unique identifier to every requirement
  • Structure natural language requirements by ordering them in sections and sub-sections
  • Avoid redundancy where possible
  • Use templates

17

18 of 47

Today’s Lecture – How can we specify requirements with natural language effectively?

  • Natural language tips
  • Templates
  • User stories

18

19 of 47

ISO/IEC/IEEE 29148 Standard

19

[ISO/IEC/IEEE (2018). Systems and Software Engineering — Life Cycle Processes — Requirements

Engineering. ISO/IEC/IEEE Standard 29148.]

20 of 47

Requirement Statement Patterns

20

Source: “The Unplanned Journey of a Requirements Engineer” by Sarah Gregory, IEEE Software, 34 (5), 2017.

21 of 47

Requirements Statement Template (Functional)

Text questions to (562) 684-8307

21

Source Robertson and Robertson (1999)

22 of 47

Requirements Statement Template (Non-functional)

Text questions to (562) 684-8307

22

Source Robertson and Robertson (1999)

23 of 47

Today’s Lecture – How can we specify requirements with natural language effectively?

  • Natural language tips
  • Templates
  • User stories

23

24 of 47

User Stories

  • User stories are the most common way to express requirements in agile processes
  • A relatively informal way to capture requirements
    • Defers details until absolutely needed
  • Can be used to derive formal requirements, use cases, and other artifacts

​

​

​

​

​

Text questions to (562) 684-8307

24

25 of 47

Today’s Lecture

  • Requirements in general
    • Purpose
    • Challenges
    • Qualities to strive for (e.g., implementable, testable, internally consistent, etc.)
  • Requirements in agile
  • Personas and scenarios
  • Use cases
  • User stories
  • Your requirements document

​

26 of 47

Text questions to (562) 684-8307

27 of 47

Text questions to (562) 684-8307

28 of 47

Sample user story

28

Source: system vision document

29 of 47

Sample acceptance criteria

29

Source: interview with resort manager 7/23/23

30 of 47

User stories should be INVEST

  • Independent
  • Negotiable
  • Valuable
  • Estimatable
  • Sized appropriately
    • 5-15 stories per sprint
  • Testable

​

​

Text questions to (562) 684-8307

31 of 47

Example: Amazon User Stories

  • As a buyer, I want to see similar items to the one I am viewing so I can make an informed decision about which one to purchase.
  • As a buyer, I want to search my order history so that I can find specific items I have bought in the past.
  • As a prime buyer, I want to see the prime results first so that I don’t have to do any further research.
  • As a seller, I want to see my payments summary so I can find out how much money is coming to me.
  • As a seller, I want to purchase shipping through the system so I don’t have to do it through the postal service.

​

​

Text questions to (562) 684-8307

32 of 47

Example: Facebook User Stories

  • As a social user, I want to send and receive direct messages with my Facebook friends so that I can communicate with them privately.
  • As a social user, I want to comment on a friend’s photo so that I can let them know what I think of it.
  • As an event administrator, I want to see who has RSVP’ed to my event so that I can plan the event effectively.
  • As an event administrator, I want to create polls, so I can get my invitees’ opinions about issues pertaining to my event.

Text questions to (562) 684-8307

32

33 of 47

More Examples

33

Application

User Story

Chemical tracking system

As a chemist, I want to request a chemical so that I can perform experiments.

Airport check-in kiosk

As a traveler, I want to check in for a flight so that I can fly to my destination.

Accounting system

As a small business owner, I want to create an invoice so that I can bill a customer.

Online bookstore

As a customer, I want to update my customer profile so that future purchases are billed to a new credit card number.

34 of 47

Common user story pitfalls

  • The “activity” part not an activity that can be done with the system
  • The “role” part not actually a user of the system
  • Acceptance criteria not detailed enough
  • Missing a “so that” part (business value)
  • Trying to make non-functional requirements user stories

Text questions to (562) 684-8307

34

35 of 47

“Activity” part not an activity of the system

“As a store manager, I want GGSM to facilitate communication and collaboration among employees, allowing us to share updates, ask questions, and coordinate our actions to efficiently run the store.”

Text questions to (562) 684-8307

35

36 of 47

“Activity” part not an activity of the system

“As a store manager, I want GGSM to facilitate communication and collaboration among employees, allowing us to share updates, ask questions, and coordinate our actions to efficiently run the store.”

​

“As a store manager, I want to message my employees so I can quickly share important updates about store operations.”

Text questions to (562) 684-8307

36

X

37 of 47

“Role” not a user of the system

“As the IRS, we want to make sure the store’s accounting is accurate so that Granny’s Goodies pays us the correct amount of taxes.”

Text questions to (562) 684-8307

37

38 of 47

“Role” not a user of the system

“As the IRS, we want to make sure the store’s accounting is accurate so that Granny’s Goodies pays us the correct amount of taxes.”

​

​

Text questions to (562) 684-8307

38

X

39 of 47

Acceptance criteria not detailed enough

“As a store manager, I want to view the profits for a previous time period so that I can see trends in our store’s successfulness.

    • Acceptance Criteria: Mangers can filter and view profit data based on parameters such as dates, different merchandise types, and online or in-person sales.”

Text questions to (562) 684-8307

39

40 of 47

Acceptance criteria not detailed enough

“As a store manager, I want to view the profits for a previous time period so that I can see trends in our store’s successfulness.

    • Acceptance Criteria: Mangers can filter and view profit data based on parameters such as dates, different merchandise types, and online or in-person sales.”

​

    • Acceptance Criteria:
      • Profit reports are only accessible by the owner and store managers
      • The report parameters selectable by the user are:
        • Date range
        • Merchandise type (pre-packaged, non-packaged, edible, non-edible)
        • Sale mode (online or in-person)
      • The report shall list totals for all profits in the time period, according to the parameters.
      • The report shall be sortable on each field

Text questions to (562) 684-8307

40

X

41 of 47

Missing a “so that” part (business value)

“As a GGSM customer, I want to sign up for the rewards program.”

​

41

42 of 47

Missing a “so that” part (business value)

“As a GGSM customer, I want to sign up for the rewards program.”

​

“As a GGSM customer, I want to sign up for the rewards program so that I can earn savings on future purchases.”

​

42

X

43 of 47

Trying to make NF requirements user stories

“As the GG owner, I want to ensure that GGSM is accessible across all platforms including mobile devices and non-mobile devices so that all employees can easily engage with the system regardless of their device, increasing user convenience and participation.”�

Text questions to (562) 684-8307

43

44 of 47

Trying to make NF requirements user stories

“As the GG owner, I want to ensure that GGSM is accessible across all platforms including mobile devices and non-mobile devices so that all employees can easily engage with the system regardless of their device, increasing user convenience and participation.”

​

“GG shall be developed as a web app, iOS mobile app, and Android mobile app.”

Text questions to (562) 684-8307

44

X

45 of 47

Summary – How can we specify requirements with natural language effectively?

  • Major problems with NL specs: ambiguities/misinterpretation, incompleteness, and contradictions
  • Natural language tips:
    • Use shall/will/should carefully
    • Avoid imprecise terminology
    • Make it measurable!
  • Requirements templates help by adding structure
  • User stories are the most common way to express requirements in agile processes
    • Follow a specific template

45

46 of 47

Homework 4

46

47 of 47

For Next Time

  • Complete Lecture 9 Pre-Work: RE Process

47