Welcome

Following on from an earlier post (see Tips for Writing Requirements), here are some more issues to keep in mind when documenting requirements.

Correct
You need to ensure that the captured requirements accurately reflect the true business need. This is an important consideration not only for the content of the requirement but also for the way it has been documented. Sometimes, analysts are guilty of capturing a requirement in such a way that it later causes confusion or misunderstanding. They also sometimes make assumptions about what the requirements need to include. This is simple to remedy though, simply have the user representatives inspect the documented requirements to ensure they really are correct.

Complete
When working on a waterfall project we must endeavour to collect all the requirements in the early stages of the project. We need to ensure that our catalogue is as complete as possible so that requests for changes are minimised during the latter stages of the project. We can use a wide array of analytical tools to expose gaps in the requirements (e.g. business process modelling, user interviews, observation, etc) but as above the most important thing to do is have the user representatives inspect the documented requirements. Spotting missing information is difficult (because it is not there to spot!) but we can help reviewers by arranging the requirements in a structured and hierarchical manner with groups of related requirements listed together. Also ensure that missing information we know about is highlighted (use of TBC or TBD is recommended).

Prioritised
Ensure the stakeholders assign a priority to each requirement. This helps with prioritisation of development, dealing with budget cuts, integrating new requirements, etc. You could prioritise using: with high/medium/low options; with a numbered scale (e.g. Fibonacci); or with MoSCoW (Must have, Should have, Could have, Won’t have).

Consistent
The last thing we need is conflicting requirements. Remember when updating a requirement to double check any related requirements to ensure that they also don’t need to be updated. If you have a large requirements document, conflicting requirements may not become apparent until they are discovered during development.

Granular
Ensure that each documented requirement is in fact a single requirement and not a in fact a narrative containing multiple requirements. Use of conjunctions like “and” and “or” suggest several requirements may have been combined. Ensuring we have this level of granularity will make editing he document much easier (e.g. removing or adding requirements). If we don’t have every requirement stated separately, a likely consequence is that readers may miss some of these requirements when reviewing.

An example of an actor goal list

In a previous post I compared the types of use cases I have used on real projects (see An Introduction to Use Cases). The simplest of these was the actor-goal list; below is an example of what such a list could look like.

What are use cases and when are they useful? What are the differences between the main types of use case?

What is a Use Case?
Use cases describe the behaviour of systems in response to interactions with actors (which might be users or even other systems). An individual use case contains the series of steps taken to achieve one particular goal, e.g. Book Hotel Room or Order Item. It also captures any exceptions to the happy-path scenario and describes how the system responds to them. Use cases are most commonly created in a textual format, written as a series of simple-sentence action steps, for example:

1. User enters ATM card
2. ATM validates card
3. ATM requests PIN
4. User enters PIN

When is a Use Case Useful?
The creation of use cases stimulates discussions with stakeholders and between the members of the project team about what exactly the user wants to get from the system and how the system will provide it. They can be used to drive out the scope of a system and to highlight the exceptional scenarios which may not otherwise have been considered. Use cases may be written to describe business processes, to drive out gaps in requirements, to act as the formal documentation of functional requirements or even to document how an existing system works.

Types of Use Case
There are a number of use case tools which can be utilised to different ends. Below is a list of the types of use case which I have successfully used on real-world projects:

• Actor-Goal List – This is the simplest format, and consists merely of a list of actors (i.e. the stakeholders who will use the system) and their associated goals (i.e. what they want the system to deliver). This can be useful to quickly capture the scope of a system. It is similar to the user story/product backlog concepts used in agile software development. You can prioritise this list to quickly derive the development priorities and proceed to uncover further levels of detail using a more in-depth use case format as and when you need to.
• Use Case Briefs – This use case format delivers the next level of detail but is still relatively simple. It provides an overall view of functionality by giving a very brief overview of the happy-path scenario for each use case we have identified. This generally takes the form of a table with columns for use case name, actors, goal and the brief itself. Use case briefs should be used to gain a broad picture of business processes within a business unit, or to capture all the functionality provided by a particular system or set of subsystems
• Casual Use Case – The casual use case format goes to the next level of detail, providing a paragraph description of the happy-path scenario and a supporting paragraph description of any alternate scenarios which may branch off from it. This level of use case would also usually state any important pre-conditions which must be true for the use case to be initiated and include the event(s) that triggers it. Whilst more detailed than the previous two categories, these are still not particularly rigorous and would generally be used for simple interactions or where time is pressing.
• Formal Use Case – This is the most detailed use case level: the happy-path and the alternate scenarios are broken down into numbered steps (as in the example above). Every scenario should be covered (and where use cases grow too large they may be split out and referenced). This type of use case will almost certainly be accompanied by some or all of the following: context, scope, level, primary actor, stakeholders and interests, preconditions, minimal guarantees, success guarantees, triggers, technology and data variations list, frequency of occurrence, open issues and resolved issues. Phew! I won’t go into the details in this post, but that gives you some idea of how rigorous a formal use case is. These should be used for complex interactions, where the audience requires a low-level description or where you are not pressed for time.

References

Cockburn, A. (2001) Writing Effective Use Cases. Boston: Addison Wesley.

Badly written requirements are the bane of a project and unfortunately they are an all too common occurrence. This is because many requirements documents are written by people with no formal training in writing requirements. Here are some simple rules of thumb to keep in mind when documenting requirements.

What, not How
Requirements should specify what we want the system to do but not how we want the system to do it. For example, a requirement should not state “provide a database for customer records”, it should state “provide the ability to store customer records”. Including implementation details within requirements is detrimental because: A) we may force an inadequate design onto the solution; and B) we may not capture the actual customer NEED behind the requirement and therefore risk not meeting the REAL requirement.

Feasible
The requirement must be achievable. If it is not immediately obvious whether a requirement is feasible ask a developer to review it.

Clear
Each requirement should be clear and concise. We do not want anyone to misinterpret a requirement because of ambiguous language or bad grammar. Don’t use a long complicated sentence where a simple one would suffice. Use acronyms for long system names to help keep requirements shorter. Avoid imprecise words like “should”, instead say that the system “shall” do something.

Structured
Requirements should be written in the format “The system shall provide…” followed by a single predicate. This helps the writer to avoid long winded sentences, helps the reader to understand what they are reading and creates consistency across requirements documents. Conjunctions like “and” and “or” are clues that several requirements may have mistakenly been combined into one.

Verifiable
You will at some stage have to prove that each requirement has been met. To this end, we must be able to verify a requirement through examination and analysis. When writing requirements consider the criteria for acceptance and avoid subjective phrases such as “easy to use” or “fast response time” which could mean different things to different people.

One of the benefits of working iteratively is that the customer has much more visibility of progress; because the system is created incrementally we can show off functionality at a much earlier stage, even before it is completed. How can the project team ensure they make the most of this?

On a waterfall project the customer can seem to drop in and out of existence as we pass through project phases in which they have traditionally had differing levels of involvement (consider how often you seem them during the requirements phase as compared to the development or testing phases for example).

On an agile project the customer is constantly involved with the project for prioritisation and release planning purposes. We should take advantage of their presence and encourage them to provide feedback on the system being developed as early and as often as possible. There are major benefits in doing so:

• Firstly, positive feedback encourages the team and lets them know they are on the right track. Nothing motivates a team like hearing a customer gushing over the latest features of the system.
• Secondly, even if the feedback isn’t positive, uncovering problems earlier is always a Good Thing. It saves us time and money as it decreases the amount of rework we are likely to have to do (i.e. re-analyse, re-develop, re-test) and reduces the likelihood of the mistake having impacted other areas.
• Plus, if they are being asked to provide feedback, the customer will feel like a part of the team and they’ll know that their input matters to us and that they are helping to shape the system (and as a consequence they’ll be more bought into the product we’re developing)

So with the above in mind, here are some ways we can get the customer more involved in the project and elicit feedback:

Stand-Up
For anyone unfamiliar, the stand-up is a meeting held at the same time every day (usually for 10-15 minutes) in which the whole team gives an update on progress (and they do it standing up). I’ve tried two formats for these meetings: a) you run round the group and each team member provides an update on what they did yesterday, what they are doing today and any blockers they have; or b) the team gathers around the iteration wall and the current owner of each story provides an update on its state and anything blocking its progress.

Whatever format your team finds most effective, it can be a great help to have customers present in the stand-up. Discussing work on stories will prompt the customer to feedback to us any changes they may be aware of. You will also find that many of the blockers in a teams path can be removed almost immediately by having the right stakeholder present (and the customer is always going to be the major stakeholder). And even if they can’t solve it there and then, at least they are aware of it and can take it away with them.

During the stand-up the customer will be updated on the progress of each story, which leads me neatly onto:

Demo
As soon as we’ve made enough progress on a story to have something we can show to the customer, we should demo it to them. It doesn’t need to be a complete story, or even a complete piece of functionality. Even if all we have is a part of the GUI or some of the business logic, the customer can immediately feedback on it and let us know if what we’ve built matches the model they had created inside their heads. Better now rather than a week later when changing it means changing ten other things too and potentially missing milestones.

Show and Tell
These are basically large-scale demos of all the functionality developed in this iteration (or release). This is a chance for the entire team to see what has been built, which is useful for two reasons: 1) it is a great ego boost for the team; and 2) it spreads knowledge of functionality amongst the team.

This is also an excellent opportunity to show off to some of the senior stakeholders, especially customers who maybe aren’t involved with the team on a day-to-day basis. The more visibility we have with those senior stakeholders and the more bought into the project they are, the easier it will be to utilise their influence. Feedback from senior stakeholders is very useful but can be difficult to get. This is a brilliant opportunity to draw it out.

Shared Workspace
On my current project I am lucky enough to have a customer representative working in our project room (two, in fact). I cannot overestimate what a difference this makes to the project as a whole.

Questions that may have otherwise taken hours or even days to get a response are turned around in a matter of minutes. Decisions about priorities or what to do with defects can be taken immediately rather than being deferred until the next stand-up. The customers are available to walk through process flows or review screen mock-ups at the drop of a hat.

Honestly, it’s awesome, and frankly it makes my life as an analyst a hell of a lot easier too. Because the customer has constant visibility of the work, nothing comes as a shock to them, and the need for change requests drops significantly.

In case the above has not yet made my stance clear I’ll repeat my final point: keep the customer involved and keep getting their feedback because it makes everyone’s job easier!