CPSC 541: Writing Excellent Requirements

Characteristics of Excellent Requirements

  • Complete: All necessary elements are present; no missing information or "To Be Determined" (TBD) items.

  • Consistent: No conflicts or contradictions with other requirements or documentation.

  • Correct: Accurately states customer needs and expectations.

  • Feasible: Implementable within budget, schedule, resources, and technology constraints.

  • Modifiable: Easy to change, with tracked history of revisions.

  • Necessary: Documents essential customer needs or regulatory functions; not superfluous.

  • Prioritized: Ranked by importance and urgency (e.g., using MoSCoW: Must, Should, Could, Won't have).

  • Traceable: Linked forward to design, code, and tests, and backward to higher-level objectives.

  • Unambiguous: Has only one possible interpretation, avoiding vague language.

  • Verifiable: Can be proven satisfied through inspection, demonstration, test, or analysis.

Guidelines for Writing Requirements

  • Evaluate from the developer's perspective for implementation and testing.

  • Document in a hierarchical, structured manner for clarity and navigation.

  • Keep sentences and paragraphs short and simple for readability.

  • Avoid long narratives; ensure proper grammar and spelling.

  • Use domain-specific vocabulary, defining new terms in a glossary.

  • Document expected behaviors and how to handle exceptions.

Tips for Clarity in Writing Requirements

  • Write requirements at fine granularity; each should be discretely testable.

  • Avoid ambiguous conjunctions ("and", "or") to prevent misinterpretation.

  • Label each requirement uniquely and organize similar ones into tables.

  • Use definitive language: prefer "shall" or "must" for mandatory requirements, avoiding "should," "could," "may."

Weak Words to Avoid

  • Minimize, maximize, optimize, user-friendly, efficient, fast, robust, flexible, and other subjective terms lacking precise, measurable definitions.

Common Types of Requirements Ambiguity

  • Ambiguity of reference: Unclear pronouns or object references (e.g., "it," "they").

  • Scope of action: Unclear definition of the action to be taken or by whom.

  • Omissions: Missing critical information, conditions, or constraints.

  • Ambiguous logic: Unclear use of logical connectors (e.g., "and," "or," "if/then").

  • Negation issues: Difficult-to-understand unnecessary, double, or triple negations.

  • Poor organization: Haphazard structure that hinders understanding and identification of dependencies.

Examples of Avoiding Ambiguity

  • Specify conditions clearly: Instead of "The system shall respond instantaneously," use "The system shall respond within 2 seconds for 95\% of user requests."

  • Use consistent terminology and define all terms in a glossary.

  • Clarify pronoun antecedents: Instead of "When the user clicks the button, it will turn green," specify "When the user clicks Button A, Button A will turn green."