Writing Clear Requirements – One Requirement Per Sentence

Having requirements for a project is essential to clarify the desired end goal and eliminate work that does not serve the end user. However, the majority of the requirements documents we review are pages of long narratives that obscure the intended end result. An example is:

Pay for product: The system should allow entry of data items relevant for customer payment, or allow a user ID to be entered to charge the amount to. If an ID is used, and there are insufficient customer account funds, then either request a credit increase or notify that the account is overdrawn and flag the account as ‘credit-line’. Email a receipt of the transaction.

The problems with a paragraph-style requirement are that:

• It takes an engineer a long time to thoroughly understand the requirement.

• The multiple “and” and “or” words add ambiguity, since the requirement, “Do A and B or C,” might actually mean only one of several possible combinations. If these are misinterpreted, then the misinterpretations are implemented as defects that are expensive to detect and correct later.

• It contains multiple requirements, some of which will be lost and forgotten by the implementer and have to be re-discovered later in test. For example, “Email a receipt of the transaction” might get lost.

• Test cases are difficult to generate that fully validate each requirement.

In this requirement, the options offered to the user are confusing since it is unclear whether the account should be automatically overdrawn or whether the user should be given other choices first.

Alternatively, one could rewrite the paragraph, specifying one requirement per sentence. For example:

1. Pay for product
1.1	User selects a) pay with credit card or b) debit ID account
1.2	User enters a) credit card or b) ID and password
1.3	If b) and insufficient funds in the ID account then offer user a credit increase option
1.4	If credit increase option not selected then notify that the account is overdrawn
1.5	If the account is overdrawn then flag the account as ‘credit-line’
1.6	Email a receipt of the transaction

 

In this style, we use one line per requirement and limit each requirement to one “and” or one “or” to avoid ambiguity. This makes the requirement quicker to read and understand. Test cases can be generated and mapped to each line of the requirement.