Intro to Software Requirements

Presentation for Evergreen Cataloging Working Group, March 10th 2020

Andrea Buntz Neiman, Equinox

Outline

• Beyond bug reports (though bug reports are still important)
• Steps of a development project (so you want to build a big thing!)
• What are requirements, and why do they matter? (reason: Happiness for All)
• Workflow experts needed! (to create requirements)
• Gathering and creating requirements (and how to make them Not Suck)
• Q&A (if you’re not tired of the subject by then)

Beyond Bug Reports

• “I want to make the software better!”
• Small fixes = Bugs
• Large fixes = Development
• Large projects = More places to misunderstand
• (Bidirectional translation is often needed)

Steps in a Development Project

1. Idea/Problem - WHY
2. Requirements - WHAT
3. Specification - HOW

​

• Development
• Testing
• Release

Defining & Researching

Coding & Executing

Discuss

Revise

Refine

What are requirements? Why do they matter?

• Requirements are WHAT
• Statements of problems, not solutions
• Atomic, correct, unambiguous, testable
• Task- or goal-oriented
• Create shared understanding
• Establish a set of parameters
• Mitigate unhappiness

Workflow experts needed

(to write Requirements, among other tasks)

Gathering requirements

• Big picture: scope & objective
• Storytelling: frame as “user stories”

IMPORTANT

• Expectations: manage them
• Knowledge gaps: known unknowns
• Reality vs. idealism
• Functional vs. nonfunctional
• Talk to other humans

A bit more on User Stories

USER STORY FORMAT:

​

As [a USER ROLE], I want [a THING/ACTION] so I can accomplish [a GOAL].

​

“As a cataloger, I want a paged chronological display of all edits, listing the user responsible and the timestamp of the edits, so I can see who was responsible for which record edits and when.”

​

The above example was taken from bug 1828279 (Wikipedia-style edit log for catalog records).

​

Atomically, this is actually 4 requirements - paged display, chronological display, user display, timestamp display - but all are CORRECT, TESTABLE, and UNAMBIGUOUS, and state WHAT you want to do and WHY.

Writing requirements

• Storytelling: stories → requirements
• Precision of language
• Stated in the positive
• Clear & unambiguous; define terms
• Abstract - WHAT (not HOW)
• Deliverability: is it testable?
• Error states: expect the unexpected
• Classification: use identifiers
• Pictures = 1000 words (approx.)

Process overview

​

​

​

​

​

​

​

2. Gather User Stories

​

​

​

​

​

​

​

1. Set Scope & �Big Picture

​

​

​

​

​

​

​

4. Extract Elements

​

​

​

​

​

​

​

3. Group Alike Stories

​

​

​

​

​

​

​

6. Write & Illustrate

​

​

​

​

​

​

​

5. Organize Workflows

Requirements: the Good, the Bad...

GOOD

• Atomic, correct, unambiguous, testable
• Define terms & don’t assume
• Based on concrete user stories
• Focused on the WHAT
• Consider error states

(Bonus good items:)

• Contain identifers
• Use wireframes as needed

BAD

• Overly broad, relying on false assumptions, ambiguous
• Presuppose knowledge and understanding
• Based on vague expectations
• Focused on the HOW
• Only considers the One Perfect User / Workflow

​

...and the Ugly

​

​

​

​

​

​

​

​

Source: https://reqtest.com/requirements-blog/10-of-the-worst-requirements-i-have-ever-seen/

Conclusion

Creating good* requirements is an important part of any large dev project.

​

Good requirements = positive outcomes for all stakeholders.

...and non-crashing MARS landers**

​

*as defined in preceding slides

** this is a true story: https://www.wired.com/2010/11/1110mars-climate-observer-report/ - miscommunications about unit conversions + assumptions about said = crashed lander

​

​

​

Questions?

abneiman@equinoxinitiative.org

IRC: abneiman

Twitter: @andreabneiman