The READ, RATT, AART Requirements Methodology

Fred Henry Williams, Williams Technical, www.williamstechnical.com

We need a better method for defining system and user requirements that includes the best of Waterfall and Agile. Using the format READ, RATT, AART for clear user and environmental specifications helps you organize, track, prioritize, develop and test systems with user and business value. Requirement specifications, test cases, user stories improve with clear writing. Combine Waterfall and Agile strengths for better requirements that provide a clear view of what users want, where, and when. This introduction to the method shows you how to organize, track, develop and deliver quality systems using READ, RATT, AART.

Waterfall and Agile aren't so starkly separated. Most organizations retain a mix of methods. Here's how it can work better, taking advantage of Agile and Waterfall strengths, and blending them together to define realistic and testable functionality.

To combine the best of Waterfall and Agile, use the acronyms READ, RATT, AART.

READing your users allows you to describe what they want, who they are, and how they'll know they got what they wanted. Share in a Waterfall style shared reference document the Results, Environment, Acceptance criteria, and Demographics for each actor in the system.

RATT states the Result required, the Actors, Test of usefulness, and Test of business value. This is a clear problem statement, with developer and QA tests.

AART is a clear statement in the simple present tense. Name the Actors, an Action, and Results. Add at least one Test of how the actors define success.

Why did we get into conflict between Waterfall and Agile in the first place?

Putting a waterfall in the background of your agile stories

Early methods for developing requirements drew from the experience of construction and military planners. Their contribution to the field is generally known as Waterfall. This is a top down method where all requirements are defined up front, and cascade down through the organization. Typically this resulted in hundreds of pages of details which were followed by the developers, tested by QA, and finally validated through user acceptance.

The waterfall method works... but it relies on an assumption of omniscience. Somehow business analysts, architects, programmers, and project sponsors are presumed to actually know the details of the implementation at the onset of the project. Few changes are allowed, except under heavily controlled conditions. Because validation and acceptance occurs at the end of the project, which might be years after the drafting and approval of requirements, new approaches and adaptations resulting from the experience of creating the system, are either glossed over or rejected.

Organizations such as the IEEE promoted this methodology through publications, training and certifications. CMMI, PMP, Prince2, Six-Sigma, ITIL and other flavors of project management and control continue to dominate the professional qualifications of the programming world. (PMBOK)

There is an excellent reason why this method still dominates the world of systems development.

Narratives mislead, but are nonetheless essential to understanding. Stories seem to be how most normal humans organize information about the world, automatically sorting an array of objective facts into hero's quests, tales of transformation, monsters slain, mountains climbed. In this process subjective facts and assumptions, which may not be true, are invariably inserted.

To avoid such errors engineers, mathematicians, and scientists developed evidence based and logically testable methods to remove narrative. This necessary step, however, replaces narrative with pure description. If modern technological systems had no effects on the lives of humans, there would be no need to change this. Omniscient description would be enough to communicate all that must be said of the world.

Yet the failures of this approach, especially as projects grow in size and complexity, have frequently embarrassed the advocates of the waterfall methodology. Over budget, late, and cancelled projects, often costing hundreds of millions of dollars and wasting untold working hours, appear in the news regularly. (Chaos report)

In response to this dissatisfying and occasionally disastrous approach, leaders of the software development industry have attempted to modify or replace the waterfall methodology. Among the approaches we have seen Extreme Programming, Test Driven Development, and Agile.

These newer methodologies reject top-down approaches, acknowledging that there is a cone of uncertainty that can only be clarified through the process of actual developing the system. In short, narrative matters. Objective facts change over the course of development. Reasoning that it is better to recognize this fact rather than cover it up, Agile rejects documentation-first approaches, favoring instead an iterative and adaptive method of delivering functionality, reviewing feedback, and changing approaches in response to user reactions. In a widening spiral, functionality is delivered according to what users value and what organizations can deliver quickly.

Empathy is the catalyst for valuable Agile requirements. Understanding and feeling for your real world actors allows you to create something they buy and use. There's usually a minimum of two actors, the user and the buyer. They want different things, and both must be satisfied with the results you offer.

The READ, RATT, AART methodology provides a practical method to improve empathy in Agile user stories, while also taking advantage of the Waterfall method of listing non-negotiable requirements.

There's no need to create elaborate background stories for your actors. Avoid the mistake of giving irrelevant details. You want to provide just enough information about their roles, experiences and expectations so they're realistic and useful.

Describe their environment in Waterfall format, with lists and tables. It's useful to list the real-world constraints that are non-negotiable. These parameters include where they work, the technology they'll use, devices and locations, legal requirements, and so on. It's a waterfall type list, with the most important criteria listed first.

Then turn your attention to their goals. What results do they want? What is acceptable? How can they know they got what they expected?

This approach also has its critics. Agile assumes that the end-user is the primary customer for a system, and that all functional requirements can be negotiated and trade-offs defined with heavy user involvement in the definition of the system. Narratives from the user perspective, heroic tales in the form of user stories, are presumed to be the only required view of the system.

In fact, few end users have the skills, time, or interest in becoming development partners. So programmers end up making guesses about what is required. The stories aren't told from the first person perspective, but a 2^nd or 3^rd person view. Essential description of time and place, environmental factors and constraints, get left out.

Examples of Agile methodology failure include systems where regulatory and legal requirements are defined through user stories, rather than explicitly stated through simple description. If you are developing an accounting system for a government agency, you cannot expect the end users to have sufficient knowledge of the underlying practices and expected levels of performance. Capturing this information in a user story is unrealistic, leading to worse problems than simply stating the requirements in formal Waterfall language.

So any narrative alone, embedding human assumptions of heroes’ journeys, and leaving out description of the landscape where the story is set, must fail to capture all the requirements. It's like a movie where you only see actors performing against a green screen. We must include the Waterfall in the background, explaining the time, place, and constraints of what happens to the actors in the Agile story.

Those who actually make systems, well-schooled in logic and the world of inconvenient facts, know this already. We have never accepted a waterfall-only or agile-only view of our work.

The result is that few (if any) organizations are only "Agile". Most seem to have instinctively created a hybrid of the methodologies, what is jokingly refered to as "Watergile". Sometimes this is superficially a renaming of waterfall artifacts with agile terminology...a true waste of time and effort which delivers nothing of value while creating confusing and chaos. Other times old waterfall requirements are forced and twisted into the agile methodology, and what was once a clear requirement becomes vague.

Clearly we all need to recognize that all methodologies have strengths and weaknesses. To strive to have perfect knowledge before a project even starts is ridiculous. And to be so adaptive and iterative that few predictions of cost, schedule, or even functionality can be reliably delivered goes against general realities of the business world.

After decades of attempting to define system and user requirements, using various waterfall and agile methodologies, may I suggest an open compromise which blends the advantages of both methodologies? With our methodology we recognize the primacy of user requirements and the advantages of stating these in narrative stories. We also recognize the real-world situation where non-negotiable requirements can never be ignored and must be incorporated into the requirements specification in a way that the developers can meet both user goals and environmental realities.

Most task tracking tools provide shared reference pages. Whether as a wiki or a document, use these to describe who uses your system, and why they want to use it.

If it makes sense you can create a Universal Environment. Like a novel, describe the non-changeable system in terms of constraints. All actors in the system inherit universal environmental constraints. Exceptions are specified within an actor's description.

Actor descriptions, in READ format:

• Results
• Environment
• Acceptance
• Demographics

Actors have background and environments that allow or require individual results.

Use these pages as references for all Agile user stories. These are the Waterfall requirements for testing. All user stories inherit Univeral requirements. All user strories specify one or more actors, and describe what the actors want, and how they can get it.

Describe environments of your stories with Waterfall

Let's look again at how our brains structure stories. At the beginning, and continuing throughout a well-written story, the author adds and expands on details of the setting. This descriptive prose is presented either from the viewpoint of the protagonist, or by the omniscient narrator. The best stories often include both views.

Within any setting, a farm house, a magic dragon's lair, a space ship hurtling through uncharted galaxies - the story must include actors doing something interesting. That’s where user stories are essential. But without the setting, the stories lack context.

So when writing requirements specifications, include both waterfall style explanations of the hard-facts which will not change, the time and place, physical characteristics, assumptions required to impose order on the system in the real world.

There are two types of description, 1^st and 3^rd person. So while defining the system, you can organize descriptions according to universal (3^rd person) and variable (1^st person) descriptions of environment.

Universal descriptive requirements cannot be broken by any actor within the system. These include system constraints and underlying architecture, integration with other systems, and limitations of what current tools can provide.

Individual descriptive requirements change according to the specific user. Mary at the front desk does not have the same level of access to a system as the CTO. A remote user cannot have the same performance expectation as the system administrator. Each actor's perspective affects their experience of the system, and how they use the system to perform their story.

Each requirement specification references the universal environmental constraints. (QA validates this in scripted testing.)

The specification references the named actors description. These actors perform actions within this environment. Use READ to format these actor descriptions.

Each actor has required results, motivations to perform the actions. Actors get results from their actions. The story specifies which actors are doing what, and the actor's background and circumstances show where, how, and when they perform their part. Use RATT for describing functionality. These can be sorted, with actors added and removed. For developers, these are functional requirements. For product owners, these are business cases for user value, and profit. If the team cannot articulate the Results, Actors, and Tests of value and profit, it's an early and clear warning that you must further define the requirement.

Using the structure of READ, RATT, AART to structure and validate user and system requirements.

Be the author of your requirements specifications by doing what authors must. Describe the setting and introduce the actors. You don't put all the details in the first chapter, but build and modify as you write. So in the first iterations of your specification, you put down the big picture.

Where you state your universal environment is up to you. It can be a section of a document, a wiki page, a set of metadata. What matters is that these statements rarely change, and are true for all actors wihin the system.

But don't impose too many of these universal requirements at the beginning. Instead, quickly move the narrative of your system forward by introducing the characters and what they want.

If your universal setting is a magical kingdom, when you introduce the actors the first thing you'll do is state whether they are kings, or wizards, knights or peasants. Is the knight rich or poor? Does the wizard work in a cave or in the castle? Is the peasant struggling with a mud hut, or a happy villager following the ancient traditions? Does the peasant's story lead to marrying into the royal family, and moving to the castle?

Users do not often care about the underlying process the system uses to get the results they want, any more than most drivers care to know the details of how their car's fuel injection system operates, or a fantasy narrative explains how the magic wands works. Our hero only wants to win the road race, or incant the right spell to transform a frog into a prince

So we start first by defining both the desires of the end user and the realities of the environment in which they will operate the new system. The results we deliver will continually evolve and expand over the life-cycle of the project, just like a novel develops and expands as you read, but the environmental constraints change slowly if at all. Most novels don't shift in the middle from slice-of-life to space opera, even though good novels do shift the experience of the characters, resulting in changes of their local environment and achievement of important goals. So it makes sense to differentiate between these two types of inputs into the requirement specification. What remains the same, what changes within the perspective of the actor, and what does the actor do to earn that shift of perspective

READ your users

Define your users first within the parameters of READ: Results; Environment; Acceptance; and Demographics. Each actor who uses the system, including non-human actors like servers, APIs, and regulators can be defined according to READ. System outcomes can be sorted acording to named specific actors. You can also sort specifications according to shared environment factors, or the expected results. By shifting the perspective between these views, you gain clarity into overlapping requirements and constraints.

Name your users. Define user demographics and environment, then determine what results they desire along with what makes that result "alright" or acceptable. If the user is another system, use the same format and name the system. In practice, these Actor descriptions appear to be persona descriptions. You can use real people, archetypes, personas, or even systems that act in your environment.

Whether you include a photo is up to you. The level of detail is up to you, and should grow and be trimmed over time. Define the four READ elements.

Results: Begin by stating the results each end user desires. Limit this to the most important outcomes the users expect. Trying to guess all required results up-front is not recommended. Better to define what matters most, and deliver that first, allowing your stories to grow over time. Use the present tense, active voice, and always start with the name of your user. For the most specific users, create lightweigh user personas in accordance with the principles defined by Alan Cooper. (Inmates Running the Asylum)

• John sees daily reports showing how many people have visited his web site.
• Mary sends weekly messages to her grandchildren.
• The system sends notifications of system performance parameters to Richard via text message.
• The file database saves all changes to files.
• Chrome browser displays the content of web pages.

Environment: For each user of the system, list the physical and technical evironment where the user will receive the results of your work. What is their operating system, bandwidth, regulatory and legal matrix in which they must use the system? This is unlikely to evolve rapidly, so there's no reason to put this information into the form of user stories. Rather you can create a list, table, or collection of links to outside definitions of the constraints the user experiences. This information resides in your user descriptions.

• Win7, broadband connection, FireFox browser.
• Open office plan. Noisy. Frequent interruptions.
• FDA regulatory oversight. Sarbanes-Oxley financial reporting.

Acceptance: Acceptance criteria of the users can be defined in qualitative terms. It's not required to declare what the perfect result will be. Rather, define what is "good enough" or meeting their expectations of how a system should work. As the peasant character in our story may be satisfied tilling his fields, as he progresses through the narrative of marrying into the royal family he'll become more demanding. This can be stated in terms of comparison (result delivered at least as fast as our competitor's product) or absolute numbers (result delivered within .003 seconds). As these expectations change, you can update these parameters. What you want to define is the condition that would prompt the acceptor of the work say the feature is "alright". Performance beyond the "alright" condition is likely to be wasted effort, over-kill that won't be appreciated.

• Faster than our previous system.
• Includes profit-loss statement daily.
• Does not prevent me from using another system simultaneously.
• Works on existing hardware.
• Costs less than 20 dollars per user per month.

Demographics: For each user of the system, define their demographic information. This does NOT require excessive information. If you are creating Personas to stand in for actual users, it's certainly not helpful to developers to find extraneous details irrelevant to the project and the results desired. It is enough to state the user's age, profession, education, and experience with similar systems. It's not helpful to include the user's imagined hobbies, family details, and the names of their pets. Only demographic information relevant to their role is required here.

• John Harris: 35, systems admin, MSDN certified, full time employee.
• Mary Smith: 67, retired English teacher, uses public library computers.
• Richard Hall: 43, project manager, 18 direct reports, Prince2 certified.

Kings in a magical realm have unique demographics. So do wizards, thieves, knights and knaves. When you tell a story, it's important to show that the characters all have a back story that explains their motivations. Demographics provide this information in shorthand, helping the developers understand the who, why, when, where of the actors using the system.

If this information is not included, or is false, the system is highly unlike to produce the expected results.

Describe proposed functionality as RATTs

All characters in a novel have a motivation. They want to find the grail, rescue the victim, climb the mountain. Without this motivation, the character has no reason to participate in the story. If there's no rat to eat, the cat will only sleep. To make it easy to remember that these motivations, or problems, are the reason people will use your system, it's instructive to think of functionality as rats.

After you have defined your system users with READ, describing the users, their setting, and their motivations, you can describe and analyses proposed system functionality using the acronym RATT: Result, Actor, Test of user value, Test of business value.

Result. For each result you listed in the user descriptions, create an instance of proposed functionality. Be specific enough to easily create a test, from the user's perspective, where they can know whether they have received the result desired. (If you cannot easily create such a test, you need to find a better understanding of the requirement before proceeding.)

Actor. Name the end user. Link to the profile that contains that user's READ information so that all environmental and acceptance information for that particular user is part of the functional description as well as the result. This is how waterfall constraints (performance, reliability, speed, legal and regulatory needs) blend with agile user stories. The environment of the individual users are a key part of every user story, and cannot be violated.

Test of user value. State how the user knows they got what they wanted. State how the user values this result. Try to include monetary, competitive, perceptual, emotional, and financial measurements to define the value the the user places on this feature. High values increase the priority of the feature.

Test of business value. How will adding this function to the system benefit the business. State this value in terms of money, time saved, capabilities expanded, or strategic goals met. If you cannot easily state at least one benefit to the business for developing a feature, question whether the result is worthwhile developing or should be abandoned as unrealistic or unprofitable.

Note: No proposed functionality should be defined any further unless both tests of user value and business value are defined and agreed to by the customers, development team, and business representatives.

This is your functional description. What do specific users get. When do they get it? Why do they want it? Why can we give it to them?

Some functional RATTs

Result: Barrack reads intercepted communications.

Actors: Barrack Obama, (President of the United States, the White House)

Test1: Barrack can discover suspects.

Test2: OurCompany can sell this service to the NSA for Barrack’s use, at 2.5M per month.

Result: Alice sends a message to Bob that Charles cannot read.

Actors: Alice, Bob, and Charles (Encryption Hobbyists, Coffee Shops and Data Center)

Test1: Charles cannot read intercepted communications.

Test2: Alice and Bob will pay $5 per month for this service.

Result: Peter creates and prints a TPS Report.

Actors: Peter (IT worker, Office Cubicle)

Test1: Peter delivers TPS Report to Lumburgh, including cover sheet.

Test2: Our IT support division is not outsourced for cost cutting.

Write user stories as AART

The important outcome of organizing information about the users, the results they require, and tests of user and business value is that it allows you to write clear specifications that can be used by developers to deliver high quality targeted functionality to your users. QA can also use these stories to demonstrate passing or failure.

To ensure this information is clear, it's important to use simple language.

The simplest form of English is the present tense active voice. The form is Subject, Verb, Object. For example, "Fred drinks coffee", or "Alice sends a message to Bob."

In Agile user stories, you should name the actor or subject first. Then describe the action the user takes to achieve a result. Follow this with at least one test, so you know when the result is delivered.

Actors:

Name the actor who performs each action. This actor is involved in a situation with a RATT. There can be more than one actor in the scene, as when a system administrator helps a user to log on to the system, or a wizard transforms a peasant into a knight.

Action:

Name an action within the system. Sir Pendelton moves into the castle, the Active Directory authenticates and authorizes a Richard, Susan, and Barrack so they can view files. The Sir Pendelton is ushered into the royal court, or Susan prints visitor's badges with names and photos.

Results:

Describe how the actors know what has changed. The receptionist Susan (link to Actor description) confirms the name on the badge is the same as the visitor's, and knight Pendleton (link to Actor description) enters the castle to see the king waiting on his throne.

Tests:

You can include as many tests as make sense. If you find you're including more than 7 +/-2 tests for a user story, you should probably break up the AART story. At a minimum you should include a test of user value. You may also want to include a test of business value for each AARTful story.

The knight Pendleton sees the crown and scepter, proving the king is on the throne. Our receptionist Susan can see the calendar and all scheduled visitors along with their details.

AART is a continuation and re-arrangement of the RATT. It's a change of focus, when the development teams describe the Action. Large (more than one sprint) AARTful user stories are Epics with related user stories. Large tests can be promoted to stories, and small stories can be demoted to tests.

(First, Copy the Actor, Result, and Test-A, and change the order.)

Actor(s): Personas/Customers have a name. Use name to link to the persona description/customer interviews.

Action: What does the actor do with the system. Explain interaction at a high level.

Result: What does the actor get at the end. The result is a "real-world" consequence, valuable to the actor.

Test-A: Acceptance test. State the user value. How does the actor know they got that result? This is a black box acceptance test.

From RATT to AART -- Barrack's Epic

The RATT product description:

Result: Identify suspects.

Actor: Barrack (link to Barrack description and environmental constraints)

Test-A: Barrack can read profiles of suspects (link to suspect description list).

Test-B: Barrack pays DefenCorp $2.6M monthly for reports.

Becomes AARTful user story:

Barrack reviews selected TELCO records which identify suspects.

Test-A: Barrack sees only suspects matching selection criteria.

Additional tests:

Test-A: Barrack uses a secure computer (link to description) to see suspects (link).

Test-A: Deliver suspect identify reports to Barrack every 24 hours.

Test-A: FBI (link), CIA (link), and NSA (link) search and sort suspects (link).

Test-A: Sample TELCO records (link) identify suspects contactsID (link to 3rdDegree API).

Test-A: Use live TELCO metadata to sort/search and export contact and activity records.

Test-B: DefenCorp can sell same system to Vladimir, Jong Un, and Bandar?

Test-B: Barrack gives TELCOs immunity from law suits in trade for metadata?

Using AART to describe the Actor, Action, Result and Tests, we can see what matters most. Before we jump to design details.

This example is an EPIC user story. It cannot be completed within one sprint. We must add acceptance tests, then convert them into smaller user stories to clarify and constrain this Epic. The existing tests should lead to additional AARTful user stories which complete the epic.

Prioritize functionality at the RATT level. When it's time to develop, use AART to define user functionality and specific tests for acceptance.

Let's promote one of Barrack's acceptance tests into valuable AARTful user stories.

Test promoted to story: TELCO records (link) identify suspects contactsID (link to 3rdDegree data standards).

RATT:

Result: Richard searches and sorts suspects’ metadata.

Actor: Richard Peters (link), NSA analyst

Test-A: Richard searches TELCO records by name, phone number, or IP address, and receives sortable suspects report.

Test-B: Essential functionality for operation to deliver to Barrack (link).

Test-B: Can Richard use existing 3rdDegree UI (link) to search/sort by suspects TELCO metadata (link)?

AARTful user stories:

* Richard searches for Osama (link) through contactsID, to see a list of suspects.

Test: Richard types contactID. Richard sees matches for Osama's contactID display. Richard uses the data for analysis, sorting, and creating reports.

* Richard analyses the list of suspects.

Test: Richard sorts the metadata to identify patterns.

Test: Richard uses graphical interface to represent patterns.

* Richard cross-references Osama with DreadPirateRoberts.

Test: Richard uses search filtered metadata to identify patterns.

Test: Richard uses search filtered metadata to visualize hypothetical patterns.

Test: Richard saves metadata and visualizations as reports for Barrack.

Tests can be moved up and down in priority, and they can be promoted to user stories.

Similarly, during sprint grooming and project planning, user stories can be demoted to tests.

Non-negotiable Waterfall type requirements can be stated as tests, and constraints are included in the Actor's Environment description. Your Universal Environment specification is tested through scripting.

Defining what is important

No one except the creator really has the goal of using technology only for itself, especially when it's technology in the form of new software. What other people want is a result that is valuable. If the result comes in an innovative form, we may consider it a world changing project. But no matter what, we want a real-world result.

Use READ, RATT, AART to define what is useful and valuable.

Development teams deserve better information in requirements, especially tests of the user and business value of proposed system features. Please do not prescribe a solution to the developers. Within the RATTs to AART process, there must be no specification of how to meet the customer's goal, only a testable description of the desired end result. Describe the magic spell, but not how the magic works!

Understanding your user's real-world goals is essential to creating requirements specifications. Reliably making something that gives someone a specific result is valuable. Delivering value lets us get paid for our efforts, as well as giving us a sense of pride and accomplishment.

READ, RATT, AART will not resolve all the problems of developing new products in the world. But openly combining both Waterfall and Agile requirements into a three level definition that provides a testable view of the world is a compromise that will reduce the documentation burden while improving developer and QA understanding of what is important for delivery.

References

SDLC high level view http://en.wikiversity.org/wiki/Technical_writing_sdlc

AART of Writing Requirements (32:11) https://vimeo.com/78057283

Original AART Proposal http://agileprague.com/pool/vzor/upload/AARTproposalDraft4.pdf

Writing AARTful Requirements (00:31) https://www.youtube.com/watch?v=3ikkOSqtKQU

How to Sabotage Projects, Part 1 (43:45) https://www.youtube.com/watch?v=Fm9_lA4bjaU

About Personas http://en.wikipedia.org/wiki/Persona_%28user_experience%29

Creating Personas http://www.usability.gov/how-to-and-tools/methods/personas.html

---

More articles on software requirements and specifications

Analysis on Analysts in Agile

Non-Functional Requirements: Do User Stories Really Help?

Something Old, Something New: Requirements and Specifications

Agile Requirements

---

Click here to view the complete list of archived articles

This article was originally published in the Summer 2015 issue of Methods & Tools