Seminar Description: "Writing High-Quality Requirements"

Karl E. Wiegers

Description: This one- or two-day seminar helps anyone performing the requirements analyst role on a software or systems development project become more proficient at specifying high-quality requirements. It presents extensive advice on how to examine requirements critically for problems and how to write clear, unambiguous requirements of various types. Many practice sessions give students experience in finding requirements problems, distinguishing requirements from design, interpreting customer input, writing precise functional requirements, specifying quality attributes, defining data items and business rules, and choosing alternative ways to represent requirements besides natural language text.

The seminar can be tailored to meet the needs of each specific audience, such as having students work with requirements pertinent to their own development project and user community. The students will not be expert requirement writers after this seminar-that takes practice and helpful review feedback from others. But students will have a good sense of what constitutes high-quality requirements of various types and how to write them. A white paper titled "Elements of Requirements Style" is included that contains much advice on writing clear and unambiguous software requirements.

Objectives: On completion of this seminar, the student will be able to:
  • Describe the characteristics of high-quality requirements
  • Critically evaluate functional requirements and quality attributes
  • Review and provide feedback on requirements written by other analysts
  • Document project scope, data definitions, and business rules
  • Describe the components of a well-structured use case
  • Write functional requirements and quality attributes that are more precise, richer in detail, less ambiguous, and more actionable than before
  • Derive functional requirements from a use case description
Audience: This course will be useful to anyone who has to document, analyze, or use requirements on a software or systems development project.
Format: Approximately 60% lecture and 40% group discussions and practice sessions.

Outline for "Writing High-Quality Requirements" (2 days)

I. Group Discussion: Your Requirements-Writing Problems

II. Software Requirements Refresher

   A. Requirements definition
   B. Three levels of software requirements: business, user, and functional
   C. Characteristics of high-quality requirements
   D. Tips for writing clear requirements
   E. To duplicate or not to duplicate
   F. How much detail do you need?
   G. Requirements vs design

III. Reviewing Requirements

   A. Peer review defined
   B. Who should review requirements
   C. Practice session: Your requirements reviewers
   D. Formal and informal review techniques
   E. Guiding principles for effective reviews
   F. Checklists for reviewing requirements

IV. Depicting Project Scope

   A. Context diagrams
   B. Use case diagrams
   C. Feature levels
   D. Event list

V. Elements of Requirements Style

   A. Structures for writing functional requirements
   B. Write in active voice
   C. Common types of requirements ambiguity
   D. Avoiding requirements ambiguity: negation, omissions, boundary values, synonyms, similar sounding words, pronouns, adverbs, i.e. and e.g., the A/B construct
   E. Weak words to avoid
   F. Avoiding solution ideas

VI. Using Multiple Requirement Views

   A. Alternative requirements views
   B. Decision tree
   C. Tables and structured lists
   D. Choosing a requirements model
   E. Listening for key words in user input
   F. Relating user input to model components

VII. Sample Requirements to Evaluate

   A. Some good functional requirements
   B. Critique several flawed functional requirements
   C. Rewrite some of the flawed requirements
   D. Using alternative requirements views
   E. Reviewing and improving your own requirements

VIII. Writing Other Types of Requirements

   A. Nonfunctional requirements
   B. Software quality attributes
   C. Writing nonfunctional requirements with Planguage
   D. Data dictionary
   E. Business rules
   F. Deriving functional requirements from business rules

IX. An Overview of Use Cases

   A. Use cases defined
   B. Scenarios and use cases
   C. Preconditions and postconditions
   D. Normal flow, alternative flows, exceptions
   E. Use cases and functional requirements
   F. Deriving functional requirements from a use case description