How to Plan a CMS Project - Requirements

What are requirements? Put simply, they are a statement of what the client wants the project to deliver. However, they should be considered a wish list of what the client would like, as opposed to what the project is to deliver. The main mistakes made with requirements are assuming that they are complete and correct. Requirements are not always an accurate representation of what the client is after. That's not because the person who wrote them got it wrong but because the person providing the requirement hasn't communicated it accurately. Sometimes people think they know what they want but don't realize until they see the finished product that it doesn't work or make sense.

It's hard to manage a project without a clear idea of what the end result is supposed to be. That's what requirements are for, to define what the end result is supposed to be, and why. Requirements provide the basis on which subsequent decisions are made, so if there is a flaw in the requirements, it's highly likely the end result will be flawed. But making requirements flawless is a task fraught with difficulties on many levels. Getting it right and having that translate in to a successful result is so risky that Fred Brooks (Mythical Man Month) suggests we plan to throw the first result away, not something most clients want to hear. Maybe the answer isn't getting the requirements perfect, but reducing the potential for errors by understanding where the risks lie.

Capturing the Vision

First and foremost, requirements should capture the vision of what the client hopes to get out of the end result. Being able to capture and communicate any vision, let alone a complex project, is a difficult task and requires great skill.

In writing requirements, the author has to consider many aspects of the project. The expectations of what the project will deliver, the audience, business processes that the solution will have to work with (if they exist), any business or technical constraints—for example, the system must be able to support x number of transactions a day, it must be able to import data from an existing system, etc.—basically, everything and anything to do with the project. The author has to distil all of this into a single concise meaningful document—no mean feat.

Why are we doing this?

Capturing the overall vision gives us the high-level view of what we are trying to achieve. The next step is defining why we are doing this, what the objective of the project is. When writing requirements, an author is generally faced with one of following three situations:

  1. The client doesn't really know what they want or why.

  2. The client can't agree on what they want.

  3. The business hasn't yet established what is it they are after in detail, nor have they established a clear business case.

In the first situation, a project is envisioned but nobody has really thought through the details of why they are doing this. It seems absurd that a business would embark on a project without really knowing why they are doing it, but it happens all the time. It might seem like a good idea, born of internal political or market pressure but there is something fundamental missing. To work out if this is the case, all you need to do is ask a couple of simple questions like: "Why are we doing this" or "What exactly do you expect to achieve from this project?"

If you can't get a clear and concise answer, then it's probably a good idea to stop and get an answer. If you don't, down the track during the midst of the project, you're going to be faced with difficult questions that are hard to answer because it's not clear what the project is all about. For example, if the objective of your project is to get more people to fill out a survey, a requirement such as "let the user save results and complete at a later date" is pretty important as opposed to "provide an something the business would value, but both cost money and making a decision on which to include comes back to the objective of the project.

In the second case, the client has a good idea of what they want and why they want it. The problem is that in most cases, there is more than one person who has a say in the project's objective and they don't all agree, i.e. you don't have consensus.

For the project manager who is trying to achieve a meaningful result, not having consensus is a very dangerous and political situation. It may seem that you have a mandate to build the project but the reality is that within the business, some people don't agree and will either deliberately or subconsciously try to sabotage the project by not providing information when required, picking holes in the project, and generally being uncooperative. The risk here is that although the end result might actually fulfil the requirements, the client is not happy because people within the business have different expectations of what the project is supposed to achieve. It's a no-win situation. The key is to get that consensus upfront.

In the final case, the objective of the project changes during development. It's often the case that when a project starts, there is an objective in mind but down the track, when the client sees the result, they realize that their vision was flawed (see Theory versus Reality). It happens all the time and it's just a part of life. Sometimes we think it's going to work out a particular way and it just doesn't pan out. It's human nature and a part of software development; there's no such thing as perfect design. But when the client doesn't read and review requirements properly because they don't want to have to think about what it is they really want (and don't hold this against the business, knowing what you want is not easy) then you can pretty much guarantee that whatever you build will need rework as the client actually comes to terms with what they asked for. Once again, it's a part of human nature to procrastinate and not deal with things unless you have to. Thinking about what you want upfront is much harder than seeing the project come to life and realizing it's not quite right—it's easy to avoid thinking about requirements; it's much harder to avoid problems when you've got a launch date two weeks away!

In the ideal world, the business people know what they want, why they want it, and what they expect to achieve from it. In the real world, it's nowhere near that straightforward and even with the best of intentions, requirements can prove to be flawed. Getting perfect requirements is not the main priority, understanding how to manage imperfect requirements is far more useful. Realizing that we live in an imperfect world is important so that we don't fall into the trap of thinking that we have got everything right upfront. That's why we need to have measures in place to qualify requirements (which is covered later in the chapter) through techniques such as defining success and defining quality, which often will put the requirements in a more realistic light and bring a pragmatic approach to the project.

Theory versus Reality

Even with the very best intentions, a clear objective, full agreement, and rigorous testing and analysis of the requirements, sometimes things still go wrong. It's the dilemma of theory versus reality. We have a theory that a particular approach will achieve a particular result, we think it through, define the approach in a set of requirements and go ahead and build it. Then we test it on the audience and find out it doesn't quite work out as we expect. It happens all the time in many industries, e.g. TV shows, films, marketing, product development. How many times has a huge Hollywood blockbuster been hyped up and still ends up flopping at the box office? No doubt, a lot of thought and effort was put into creating the movie and it was probably even put through test viewings and rework—but still it flops even with all that work.

Software development is no different; we are producing something new and even with the best requirements, functional and usability testing, it can still turn out not achieve the original objective. It happens so often that Fred Brooks (Mythical Man Month) declared that we should plan to throw the first one away. It would be wonderful to be able to tell the business that "we've got the requirements and will build your project but when you get it, you'll have to throw it away and pay for us to build another one", but I can't see it going down too well. As, to quote Fred Brooks again, there is no silver bullet, all we can do is as much as we can to minimize the risk of things not working out as expected. The first step of which is to ensure the requirements are as realistic as possible.

Formats

Requirements come in all shapes and sizes: the written word, visual prototypes, or simply ideas in someone's head. In essence, a requirements document should contain a series of statements about what the end system has to achieve. Sometimes, this includes diagrams, flowcharts, uses cases, etc. but it's not mandatory. There is no perfect way to capture requirements.

There is no consensus in the industry on how best to capture requirements or even consensus within particular methods. Depending on the nature of the project and the nature of the client, one method might be more appropriate than another. The key is to make sure that it captures the vision as effectively as possible; in some cases the written word might be effective, in other cases, diagrams, pictures, flowcharts. etc. might be necessary to convey the vision. The key is to make sure everyone is on the same page and agrees on the content. How to go about it comes down to what works best for you and the client.

The Author

More often than not, writing requirements is the job of a single person. This is both a good and a bad thing. On the plus side, a single author promotes consistency, which is important. On the minus side, if the author is not good at capturing requirements you'll end up with consistently bad requirements. Then there is the question of whether the author is internal or external, i.e. is (s)he a part of the business or is (s)he a part of the software development team (e.g. a business analyst)? Once again, there are pros and cons associated with both situations. If the author is internal, they are likely to have a better understanding of the business so the requirements will be better informed from that perspective; however, the author might have a particular bias, which will be translated to the requirements. The key is not so much whether the author is one person, a team, internal, or external but whether the right person/team is doing the job. Like almost everything in software development, it comes down to having the right person for the job.

Interpretation

In the study of law, one of the first things taught is statutory interpretation. This is a set of rules used to interpret legislation. The reason these rules exist is that the written language is not precise and can be interpreted in different ways. The "true" meaning of a piece of legislation, or a poem or even a painting is open to interpretation. The same applies to requirements. The client and author may have the same interpretation of a particular requirement and be in total agreement. Then, it is given to a developer who has their own interpretation and the end result turns out very different to what the client expected.

Get ten people in a row, give the first person a piece of paper with a sentence on it and get them to whisper it to the next person and so on down the line until the last person writes down what they were told. You can almost guarantee it will be different to what you started with. With requirements, there's the client who conveys what they want to the author, who interprets it into the requirements document, which is then interpreted by the project manager and the architect before being given to the developer who then converts the requirement to working code, which is then tested by a tester who interprets what the developer has produced against their reading of the requirements. Given the number of ways a requirement can be interpreted and how many people are involved, it's all too easy for things to go astray.

There are some simple techniques that can help to reduce the potential margin for error in interpretation. An effective technique is to create a glossary of definitions (you'll notice that the start of any contract or piece of legislation is a set of definitions). This helps to ensure everyone is talking about the same thing. You'd be surprised how often a word can mean different things to different people at different times! Another useful approach is to use consistent language—that of the client—use the words they use to describe something and make developers use the same terms, e.g. if the client calls customers passengers, use the term passengers, not customers!

Knowing How Much Detail to Capture

Avoid requirements at your own peril. You would not build a house without a set of plans; software is the same. However, there is a point where you can spend too much time defining things and never actually produce anything. The key to requirements is to define what the end result is supposed to be, and not work down everything to every last detail; that should be left for the specification. Remember requirements are about what the solution is to deliver, not how it is to be done.

The Last Word

Writing requirements is a daunting and dangerous task. Without them, a project is almost guaranteed to fail or end up taking far more time and money to produce than it needs to. With them, there's still the risk of the end result being wrong or flawed.