User Story and Acceptance Criteria: writing precise and understandable requirements

User Story and Acceptance Criteria: writing precise and understandable requirements

Let's get to the same page,

The word requirements means different things to different people. Business Management's notion of requirements could be a high-level product concept or a business vision. A developer's requirements might look like user interface designs, systems requirements, and acceptance criteria. User-provided requirements often are just user needs.

Below I will cover some 10 rules for writing User Stories and Acceptance Criteria, sometimes referring to both as 'requirements.' This can help any role involved in the requirement creation process (e.g., Product Manager, Business Analyst, System Analyst).

The Scrum participants might have different expectations of how much requirements details to expect. On the one hand, the Product Owner (PO) would love to drop the User Story or Epic, and everything would magically appear. On the other hand, DevTeam would need as many details as possible, limiting the time for the clarification process and focusing on development. From my experience, less experienced and less cross-functional the team is, more details are required. But even the experienced, cross-functional team would need a necessary level of details and precision, so they don't need to guess what PO is expecting and aren't quite sure what to build.

To address that the PO needs clearly and precisely with the necessary level of details, prepare the requirements.

And to do so, you should start with correct Grammar and Spelling. That is the base. 

We interpret language based on the rules of grammar. Incorrect grammar leads to ambiguity and clouds understanding. This is especially true when the recipient of the requirement learned the language the requirement is written in as a second language using specific grammar rules. If these rules are not followed, that person may misinterpret the meaning of the requirement.

For the same reason, incorrect spelling can lead to ambiguity and confusion. Some words may sound the same, but depending on the spelling will have an entirely different meaning. For example, "red" vs. "read" or "ordinance" vs. "ordnance." 

Most like you already use Grammarly or similar tools, and you would address most of the grammar errors. However, there is a set of rules specifically important for requirements (here is what our product REQFORGE that can help with those and not only).

To be clear - the ultimate symptom of vague requirements is that developers must ask the PO or customers many questions or guess what is really intended.

Let me share the 10 rules that can help address the most common mistakes and save you a lot of time and cut a big chunk of miscommunication between you as a PO and the DevTeam.

Rule #1: Conform to a defined structure.

Patterns for individual requirement statements help ensure consistency. And Well-structured requirements allow an understanding requirements to be assimilated without undue cognitive loading on the reader.

US: This is pretty straight forward when we are talking about User Stories. Stick with common structure:

     “As a [persona], I [want to], [so that].”  [1]

When we talk about Acceptance Criteria, there are 2 ways to go: EARS [2] and Gherkin [3].

I prefer the EARS format since I find the Gherkin format overwhelming in a lot of cases. However, if you use Cucumber for test automation, definitely use Gherkin, since it was explicitly designed for that. 

Rule #2: Avoid the use of "not."

The presence of "not" in a requirement implies "not ever", which is impossible to verify in a finite time. Rewriting the requirement to avoid the use of "not" results in a clearer and, most importantly, verifiable requirement.

User Story

❌ Unacceptable: As a user, I want not to enter my credentials every time, so that I can access my account.

✅ Acceptable: As a user, I want my credentials automatically filled out, so that I can access my account without re-entering them.

Acceptance Criteria

❌ Unacceptable: The system shall not fail.

✅ Acceptable: The shall have an Availability of greater than or equal to 95%.

Exceptions:

It may be reasonable to include "not" in a requirement when the logical "NOT" is implied, for example - "The LogIn form shall not be red in color." Which is stating a constraint and is a verifiable requirement, as long as the range of shades of red is stated (RBG rr, bb, gg range, or a "name" of red in some standard). :)

Rule #3: Use the active voice in the main sentence structure. (For User Story, it mostly applies to 'I want' part.)

The active voice requires that the entity performing the action is the subject of the sentence, not the sentence's object. If the entity responsible for the action is not identified explicitly, it is unclear who or what should perform the action making verification of that requirement very difficult.

User Story

❌ Unacceptable: As an online shopper, I want filters to be applied, so that I can find what I want.

✅ Acceptable: As a user, I want to apply search filters, so that I can find an item.

Acceptance Criteria

❌ Unacceptable: The Identity of the Customer shall be confirmed.

✅ Acceptable: The Accounting_System shall confirm the Customer_Indentity. Note that" Accounting_System", "confirm", and "Customer_Indentity" must be defined in the glossary.

Rule #4  Avoid the use of pronouns and indefinite pronouns.

Repeat nouns in full instead of using pronouns to refer to nouns in other requirement statements.

Pronouns are words such as "it", "this", "that", "he", "she", "they", and "them."

When writing regular texts, pronouns are a useful tool for avoiding the repetition of words; but when writing requirements, pronouns are effectively cross-references to nouns in other requirements and, as such, are ambiguous and should be avoided. 

This is especially true when requirements are stored in a Requirements Management Tool (e.g., JIRA), where they exist as single statements that may not be in order. To avoid these problems, repeat the proper nouns rather than using a pronoun.

Indefinite pronouns are words such as "all", "another", "any", "anybody", "anything", "everybody", etc. Indefinite pronouns stand in for unnamed people or things, making their meaning subject to interpretation, ambiguous, and unverifiable.

User Story

❌ Unacceptable: As a site member, I want to describe it, so that others can learn about me.

✅ Acceptable: As a site member, I want to add a profile description, so that others can learn about me.

Acceptance Criteria

❌ Unacceptable: The controller shall send the Driver his itinerary for the day. It shall be delivered at least 8 hours prior to his Shift. 

{This is unacceptable because the requirement is expressed as two sentences (Rule 5), and the second sentence uses the pronouns "it" and "his."}

✅ Acceptable: The Controller shall send the Driver_Itinerary for the day to the Driver at least 8 hours prior to the Driver_Shift. 

{Note use of the glossary to define terms and to be explicit about the relationship between the Driver, Shift, and the itinerary for that particular Driver.}

Rule #5:  Avoid combinators.

Combinators are words that join clauses, such as "and", "or", "but", "as well as", etc. Their presence in a requirement usually indicates that multiple requirements should be written.

User Story

❌ Unacceptable: As a UI designer, I want to create and view an issue, so that I know what to test.

✅ Acceptable: As a UI designer, I want to create an issue, so that I know what to test / As a UI designer, I want to view an issue, so that I know what to track and test.

Acceptance Criteria

❌ Unacceptable: The User shall either be trusted or not trusted. 

{This is unacceptable for a number of reasons. The intention is that a user should be classified in one of two ways, but it is also a passive requirement (Rule #3), and it is ambiguous: the requirement would still be met if the system took the option of treating all users as trusted.}

✅ Acceptable: The Security_System shall categorize each User as one of the following: Trusted, Not_Trusted. 

Rule #6: Use a defined convention to express logical expressions.

Define a convention for logical expressions such as "[X AND Y]", "[X OR Y]", [X XOR Y]", "NOT [X OR Y]".

As with the other rules and characteristics, we want to keep requirement statements as one thought with singular statements. Thus, we avoid using "and" when it involves tying two thoughts together. However, it is acceptable to use "AND", "OR", and "NOT" in a logical sense when talking about conditions to which the verb applies. For User Stories, it is also acceptable to use "AND", "OR", and "NOT" for 'so that' part.

Examples of conventions:

1. Place conjunctions in italics or in all capitals (AND, OR, NOT) to indicate that the author intends the conjunction to play a role in a condition. And even better place conditions within square brackets, also using the brackets to control their scope. For example - "[X AND Y]."

Further use of "and/or" is non-specific, and therefore ambiguous. The most common interpretation of the expression "and/or" is as an inclusive or: either X or Y or both. If that is the intention, it should be written as two requirements, each of which can be verified separately.

User Story

❌ Unacceptable: As a user, I want to receive notifications via emails and phone text message, so that I stay updated.

✅ Acceptable: As a user, I want to receive notifications via emails, so that I stay updated / As a user, I want to receive notifications via phone text message, so that I stay updated.

Acceptance Criteria

❌ Unacceptable: The Engine_Management_System shall disengage the Speed_Control_Subsystem when the Cruise_Control is engaged and the Driver applies the Accelerator. 

{This is unacceptable because of the ambiguity of "and" could be confused with combining two separate thoughts. Instead, use the form of a logical expression [X AND Y].}

✅ Acceptable: The Engine_Management_System shall disengage the Speed_Control_Subsystem, when [the Cruise_Control is engaged AND the Driver applies the Accelerator].

Rule #7 -  Avoid the use of vague terms. (This one is mostly violated)

Avoid words that provide vague quantification, such as "some", "allowable", "several", "many", "a lot of", "a few", "almost always", "very nearly", "nearly", "approximate", etc.

Avoid vague adjectives such as "ancillary", "relevant", "routine", "common", "generic", "significant", "typical", etc. 

Vague adjectives can lead to ambiguous, unverifiable requirements that do not reflect the stakeholder expectations accurately.

Adverbs qualify actions in some way and are particularly troublesome. Avoid vague adverbs, such as "usually", "approximately", "sufficiently", "typically", etc. Vague adverbs can lead to ambiguous, unverifiable requirements that do not reflect the stakeholder expectations accurately.

As a general rule, words that end in "-ly" often result in ambiguity.

User Story

❌ Unacceptable: As an editor, I want to autocorrect some mistakes, so that I have a proper doc.

✅ Acceptable: As a doc editor, I want to autocorrect detected spelling mistakes in an active document, so that I have no spelling mistakes in the doc.

Acceptance Criteria

❌ Unacceptable: The Flight_Information_System shall display the Tracking_Information for relevant aircraft. {This is unacceptable because it does not make explicit which aircraft are relevant. Additionally, the statement allows the developer to decide what is relevant; such decisions are in the province of the customer, who should make the requirement explicit.}

✅ Acceptable: The Flight_Information_System shall display the Tracking_Information of each Aircraft located less than or equal to 20 kilometers from the Airfield. {Now it is clear for which aircraft the information needs to be displayed. Note that "Aircraft", "Tracking_Information", and "Airfield" must be defined in the glossary.}

Rule #8 - Provide specific measurable performance targets appropriate to the level at which the requirement is stated. (might looks the same as the previous rule but has slightly different focus)

Some words signal unmeasured quantification, such as "prompt"," fast"," routine"," maximum"," minimum"," optimum"," close quickly"," high speed", " user-friendly", etc. These are ambiguous and need to be replaced by specific quantities that can be measured.

User Story

❌ Unacceptable: As a passenger, I want to get my taxi promptly after I press to confirm the pick-up point, so that I don't have to wait long.

✅ Acceptable: As a passenger, I want to get my taxi in less than 120 seconds after I press to confirm the pick-up point, so that I don't have to wait long.

Acceptance Criteria

❌ Unacceptable: The system shall use minimum power.

✅ Acceptable: The system shall draw less than or equal to 50W of main power.

Rule #9 - Avoid using unachievable absolutes.

An absolute, such as '100% availability', is not achievable. Think ahead to verification: how would you prove 100% availability? Even if you could build such a system, could you afford to do so?

Other examples to avoid are "all", "always", and "never" since such absolutes are impossible to verify without an infinite number of verification activities.

User Story

❌ Unacceptable: As a Traveler, I want to know my precise location updated in real-time, so that I don't get lost. 

✅ Acceptable: As a Traveler, I want to know my precise location every second, so that I don't get lost.

Acceptance Criteria

❌ Unacceptable: The system shall have 100% availability. 

{This is unacceptable because 100% is an absolute that is impossible to achieve and verify.}

✅ Acceptable: The system shall have an Availability of greater than or equal to 98%.

Rule #10 - Avoid stating a solution unless there is a rationale for constraining the design. (This is my favorite one, as a Product Manager, I often jumped in this trap.)

Focus on the problem "what" rather than the solution "how."

Every system endeavor should have a level of requirements that captures the problem to be solved without involving solutions. User Stories and Acceptance criteria should provide a high-level specification of the overall solution. And the way of implementation should be a black box from the PO perspective. A quick symptom that the requirement consists of a solution - you are using technical terms or jargon of the DevTeam. :)

Another suggestion - when reviewing a requirement that states a solution, ask yourself, "for what purpose?" The answer will reveal the real requirement.

The solutions constrain the development and often are discarded by a DevTeam. Don't tell me that I didn't warn you. :)

User Story

❌ Unacceptable: As a user, I want to join DebtTable1 with DebtTable2, so that I can make a payment list.

✅ Acceptable: As a user, I want to see the money that I owe, so that I can make a payment list.

Acceptance Criteria

❌Unacceptable: By pressing a button on the traffic-light pillar, the Pedestrian signals his presence, and the light turns red for the traffic to stop. 

This is unacceptable because this requirement contains solution-based detail.

✅Acceptable: The Traffic_Control_System shall allow the Pedestrian to signal intent to cross the road.  

This requirement allows freedom in determining the best solution, which may be a means of automatic detection rather than button pushing. Keep in mind that "Pedestrian" should be defined in a glossary.

Those are a small part of what should be done to have excellent requirements. You need to keep the context, adhere to internal or industry-specific words and abbreviations, and many other rules that I will cover in future publications.

But following the mentioned rules for writing and investing a little bit more time during Backlog preparation and finetuning your User Stories with Acceptance Criteria, will save you a lot of time during the development. Moreover, DevTeam will love you because they can do what they love to do - develop a technical solution, and not get into the meetings and clarify what the Product Owner meant in the first place. 

References:

[1] https://www.atlassian.com/agile/project-management/user-stories

[2] https://ieeexplore.ieee.org/document/5328509

[3] https://cucumber.io/docs/gherkin/

[4] INCOSE Guide for Writing Requirements