Bad Practices - Part I - Ambiguity

I have been focusing on good practices to employ when gathering and articulating requirements. For the next series of posts I will be discussing things to avoid. The first bad habit would be to introduce ambiguity to requirements.

Requirements are intended to further understanding. Great care must be undertaken to ensure that their meaning is understood. What happens when they are not clear?

One can say, "To maintain the ecological & environmental balance within the facilities, when using transportation services ensure the facilities remain in a locked-down state.” Alternatively, one can say, “When you enter & exit the building, close the door.” By using excessive language, the underlying meaning can be lost or misinterpreted.

If one has to go over a requirement three, four, five or more times; the requirement is most-likely unclear and ambiguous. Even worse, what if everyone thinks they understand but their interpretations are all different? What is the consequence of this to a project?

My tips for reducing ambiguity are:

1. Be brief. Revise. Rewrite. (Sounds familiar - See my post 3 simple rules for business writing.)
2. Try to view the requirements from the perspective of someone else.
3. Review with different users.

The acid test for understanding - Can someone who has no knowledge of my project understand what is going on by reading my requirements?

Good Requirements - Part VIII - Design Independence

I have seen people call requirements by names such as: business requirements, functional requirements, functional specifications etc... To me a rose is a rose is a rose.

I normally use a very simple document structure to store my requirements. The level of detail increases as one moves from the Business Strategy to the High-Level Business Requirements to the Functional Requirements and finally to the Functional Specifications.
This setup allows for full traceability.

The high-level business requirements and functional requirements should be written to be design independent. This is one of the most important guidelines that should be followed. High-level requirements must answer the what question. If high-level business requirements try to answer the how question, it may bias or jeopardize the solution.

One of the problems with allowing a high-level requirement to be design dependent is that the true requirement may be obfuscated. Consider this, on one requirement gathering session I was told that, "We need the ability to clear the cache (on a server.)" After a lot of investigation, I found out that the actual need was, "the ability to publish content to a web site." If the original articulation of the need was used, the final solution could have been very different and not met the need.

That is the pitfall that one can run into when high-level requirements are not design independent.

Good Requirements - Part VII - Feasibility

To summarize the previous 6 posts:

1. Present requirements as simple, eloquent and atomic statements. By doing this, one increases the clarity and ease of testing them.
2. Define a structure for your requirements. This will allow one to determine the completeness of a body of work as well as make it easier to attain consistency.
3. Another benefit of a defined requirement structure is that it can make one's body of work more traceable. End-to-end traceability increases confidence.

This post will talk about requirement feasibility. For requirements, feasibility means that a requirement can be accomplished within cost and schedule. Personally, I find determining whether a requirement is feasible or not to be a difficult thing.

There are no easy guidelines for determining what is feasible. People, groups and companies have different competencies; thus what is feasible for one group may not be feasible for another group.

During the initial requirements gathering stages, I suggest focusing on making requirements succinct and complete. I feel that the requirement gathering process should answer the question, "What do you need?"

To determine if something is feasible or not, is an attempt to answer, "How do we do it?" By adhering to my previously mentioned guidelines, one will allow solution architects and system designers to understand and attempt to answer this question.

Good Requirements - Part VI - Traceability & Modularity

Have you ever found yourself having to respond to questions like:

• What requirement drove this feature?
• How did we implement this requirement?
• Is this requirement associated with others? Which ones?
• Can you show me how you met my needs?

Answering these questions is much easier when one's requirements are fully traceable. Traceability implies that requirements are uniquely identifiable and can be tracked. Traceability must go backward and forward (i.e., from user tests and design documents back through to high-level requirements and vice versa) for maximum benefit. Being able to show this, reinforces to the business community that their needs are understood and illustrates how they will be met.

The picture above illustrates how high-level requirements have been decomposed into low-level requirements. The screenshot is of Telelogic DOORS. The information in the High-Level Requirements column and the information in the Low-Level Requirements column exist within separate documents. Using this view, one can see whether there are low-level requirements defined for a high-level requirement. This will show one where work still needs to be done. The little arrows indicate that there is a link between a requirement and another one.

Another benefit of requirements management tools is the ability to see what requirements are affected when a requirement is changed. View the picture below and note that if one changed the Color Availability requirement one may possibly have to modify the 3 children of this requirement. Also note that the acceleration, emission standards and security features requirements (and their children) will not need to be modified.

I have found full blown start-to-end traceability to be a nightmarish task within MS Word and MS Excel. I strongly suggest that one makes use of the latest requirements management tools available. See my Good Requirements - Part IV - Be Consistent posting for some commercial products. Requirement management tools allow one to see the relationship between requirements and thereby manage them more effectively.

Good Requirements - Part V - Be Verifiable

At some point in a project the question, "Did we meet the requirement?" will be asked. This seems like a simple yes / no question, but sometimes, there is no eloquent answer. At times, development staff may produce something similar but not as articulated while at other times the articulation of the requirement itself will make it difficult to verify success. In this posting, I will be focusing on how to articulate requirements to enhance the ability to verify that they have been met.

Consider the following two examples:

Example 1 - A traditional "prose-like" articulation of requirements
A sports car that goes from 0-60 mph within 5 seconds, meets local emission standards and has a 6 speed manual transmission system. There will be a 6 disc CD changer and a DVD player available.

Example 2 - An atomic articulation of requirements
Accelerates from 0-60 within 5 seconds.
Meets local emission standards.
Available with a 6-speed manual transmission.
Option for a 6-disc CD changer.
Option for a DVD player.

Now, suppose that the car accelerates from 0-60 in less than 5 seconds, meets emission standards (in the applicable locals), has a 5 speed manual transmission and has a 6 disc CD changer but no DVD player. In example one, is the requirement met or not? Fully? 60%? Yes? No?

In the second example it is very clear that the 1st, 2nd and 4th requirements have been meet while the 3rd and 5th requirements have not been met.

The point I am trying to express is that by stating requirements as simple atomic statements the ability to easily verify them is enhanced significantly. All requirements must be testable. At the end of the day, one must show a solution adheres to its specifications. This is imperative towards building credibility with one's clients.

Good Requirements - Part IV - Be Consistent

If requirements are used to define how a system should function or behave (in the case of non-functional requirements, system characteristics), what does it mean when requirements conflict? Ok, that was a rhetorical question. Stated plainly, the answer is that there will be confusion about what to do.

When one gathers requirements, one will generally talk to a few different people. During the course of this exercise inconsistent requirements may be collected. Unfortunately, most of them are not discovered immediately. By itself, a requirement is neither consistent nor inconsistent. That judgment is determine when requirements are examined against each other.

One way that conflicting requirements can be discovered is by ensuring that requirements are categorized properly and then reviewed category by category. Anyone who as gone through the painful exercise of ensuring consistency throughout a 100+ page MS Word document can understand why categorization and physical grouping is helpful.

I suggest using a requirements management product such as Telelogic DOORS, IBM Rational Requisite Pro or Borland CalibreRM when one is working on projects. All of these products provide good requirements management capabilities such as versioning, status, approvals and linkages (to complementary requirements.)

Good Requirements - Part III - Be Clear

If one is ambiguous and confusing when articulating requirements, there is almost no chance that an optimal solution can be reached. After all, the goal of requirements is to clearly articulate the needs of a system. If one does not have clear requirements, what exactly is being developed?

Being clear may sound easy to do but understand that people may interpret the same thing in different ways. Simple terms such as cold, hot, small, tall, fast and easy-to-use mean different things to different people. 10 degrees Celsius may be cold to one individual yet hot to another.

One may not even realize that a lack of clarity exists because everyone thinks they understand a statement perfectly. So how does one ensure that there are no misunderstandings?

1. Use exact terminology and language. Some examples of clear requirements are, "The screw must be 4.5" long," and, "The screw must be able to withstand 450 degrees Kelvin." Note how much more clear those two statements are than the following one, "The user interface must be user-friendly." What does user-friendly mean exactly?
2. Use short sentences and simple language. Writing requirements is not like writing prose. In fact, requirements do not even have to be complete sentences!
3. Hold informal and formal review sessions with the providers of the requirements and the recipients of the requirements (i.e., business & IT groups.) Go over all of the requirements, including the ones that look blatantly obvious.
4. Be anal! If there is even a remote chance that someone can misunderstand a requirement, they will!
5. Clear up any issues ASAP.

The goal is effective communication. This means no misconceptions, misrepresentations or misunderstandings.

Good Requirements - Part II - Be Complete

Every requirement that is produced should express a whole idea or statement. Not multiple ideas and not parts of one.
Consider the following:

1. The screw must be 4" long, require a Philips screwdriver and be able to withstand 500 degrees Kelvin.
2. The screw is for woodwork.

The first statement has multiple components to it. If one meets 2 of the 3 parts, would one consider the requirement to be met? It is easier to look at the requirements when they are decomposed into separate statements such as, "The screw must be 4" long. The screw will require a Philips screwdriver. The screw will be able to withstand a temperature of 500 degrees Kelvin."

The second statement tells one what the screw will be used for however, it does not provide any additional details. Is the screw for holding together arts and crafts or will the screw be required to support load bearing structures such as shelves and chairs? The requirement does not provide sufficient clarity.

Complete requirements aid understanding which increases the likelihood that a viable solution can be provided.

As an aside note:
One practice that I employ is to create my initial set of requirements at a very high-level. As the requirement gathering process continues I will decompose a high-level requirement into more atomic statements. I find this to be a useful exercise because some of my stakeholders enjoy seeing the big picture while others want to look at the details. This practice allows me to be able to meet both of their needs. There are also traceability gains from doing this, but that will be discussed another time.

Good Requirements - Part I - Be Correct

As I was developing as a business analyst, I encountered guidelines that helped me articulate requirements more effectively. The origin of these guidelines was a small card from a company that became a part of Telelogic AB. I would like to share this knowledge with you.

Be Correct
A requirement must be technically and legally possible. One must not violate any legal parameters placed on the company and system in question. A company's legal counsel and government agencies should provide a good foundation for information about legal considerations. Remember that ethical considerations must also be taken into account.

I have heard people say that given time and resources (i.e., money and people) any problem can be solved. Personally, I do not subscribe to this way of thinking. When I was in university I took a course entitled Intractability & Computability; I did quite poorly, but that is besides the point. The premise of Intractability & Computability was to determine whether mathematical problems could be solved algorithmically. What I soon discovered (other than I had issues spelling the name of the course) was there were problems for which one could not reach the best solution. An optimal solution could be achieved in some cases but not the best solution. An example of this type of problem is what is referred to as the traveling salesperson problem (TSP). The traveling salesperson problem is considered np-hard.

The problem is as follows:

• A salesperson must visit X cities.
• The salesperson must minimize the distance traveled.
• The salesperson must only visit any city once.
• All cities must be visited only once.
• The trip ends when all cities are visited and the salesperson returns to the starting city.

1. Figure 1. Shows the cities and the distances that to be traveled.
2. Figure 2. Shows a path that would be undertaken (assuming A is the start.) The path was chosen by selecting the route to a city that has not been visited and has the shortest distance. Using this methodology, the optimal path is ABCDA, which is 19 units long.
3. Figure 3. Shows another path, ABDCA, which was chosen by me that is only 14 units long. This is a better path than the optimal solution, but the mathematical algorithm was unable to find it.
   

Another good reference for the TSP problem is Mathworld.

While I would not expect to encounter situations where the best solution cannot be discovered in practice, one must be cognizant that such situations can exist. How does this tie back to the be correct guideline? TSP is an example of a problem where it is not technically possible to find the best solution, merely an optimal one. Always remember a requirement must be stated in a manner that allows it to be technically and legally possible.

What are requirements? SDLC?

Functional Requirements

In order to understand what requirements are, it is necessary to know why one needs them. Basically, requirements are statements that indicate what a system needs to do in order to provide a capability (i.e. utility or benefit.) Requirements are generally prepared during the early stages of a project's system development lifecycle (SDLC.)

There are many different SDLC methodologies that are used in practice. They range from heavy-weight ones, such as the Rational Unified Process (RUP), Waterfall and Spiral methodologies to more agile methodologies such as Extreme Programming (XP), SCRUM and Crystal. Regardless of the methodology employed there are generally six basic phases (note the descriptions oversimplify the activities that occur during each phase):

(1) Discovery - "What needs to be build?" Where the bulk of the analysis (requirement gathering) occurs.

(2) Planning - Perform planning to determine the tools, procedures, budget and resourcing needs.

(3) Design - "How are we going to get a solution?"

(4) Build - Develop the solution.

(5) Implement - Deploy the solution into production.

(6) Warrantee - Monitor the solution to ensure that it functions properly, is reliable and predictable.

Requirements describe what users want a system to be able to do. Thus, well defined requirements are critical to the success of a project.

A large majority of all software defects and failures are directly attributed to bad requirements!

In practice, the percentage of errors during a project's SDLC are higher during the analysis phases than the later stages. Furthermore, the cost to fix an error increases the later the error is discovered. Put another way, the cost to fix an error during the implementation stage is several magnitudes larger than the cost to fix the same error during the analysis stage.

I have seen many different names used for requirements documentation including: business requirements, user requirements, functional requirements etc... Individual organizations will use these terms differently. Personally, I view the disctintion between different types of functional requirements to be based on the level of detail provided.

For example, a high-level (business) requirement may be, "The ability to maintain a product catalog." A lower-level requirement (functional specification), would be, "The ability to specify a date range dictating when a product is available." A good practice is to avoid mixing different types of requirements together in the same document.

Non-Functional Requirements

Most of this post deals with functional requirements. There is another type known fittingly as non-functional requirements. Non-functional requirements describe system characteristics such as:

(1) Productivity - How much a system aids users? For example, "We used to be able to handle 10 complaints in an hour and now we can handle 12."

(2) Performance - How fast should the system be?

(3) Capacity - How much traffic must the system be able to handle?

(4) Scalability - How easily can the system be expanded to handle increased throughput?

(5) Availabilty - Does the system need to be 24/7, weekdays only etc...?

(6) Recoverability - How quickly should the system be made operational after an outage?

(7) Integrity - How predictable and reliable should the system be?

(8) Exception handling - How will processing exceptions be handled?

(9) Logging - Do we need to have audit trails of activities?

(10) Security - What are the security characteristics?

(11) Manageability - How easy is it to manage the system?

(12) Useability - What interfacing is required for end-users?

(13) Interoperability - Does the system need to be able to interface with other systems? How?

(14) Extensibility - Can the system be expanded to support new functionality?

(15) Maintainability - How readily can the system be understood? How extensive is the documentation.

(16) Upgradeability - How easy is it to upgrade the system?

(17) Portability - Can the system be moved to other platforms easily?

(18) Deployability - How can the system be deployed? In components or all at once?

(19) Data Currency - How up-to-date should the information be? Real-time?

(20) Data Retention - How long does data need to be kept for?

(21) Internationalization - Does the system need to support multiple time zones, languages and standards?

Summary

• There are functional and non-functional requirements.
• Requirements are important to the success of a project.
• Requirements can be stated at varying levels of detail.

My next few posts will outline suggestions on how to write more effective requirements. Thanks for taking the time to read my blog.

P.S. I would also like to thank the colleague of mine who created the list of non-functional requirements that I have represented in my post!

3 simple rules for business writing

In order to communicate effectively in a business environment, clarity is required. This is one of the most desirable qualities for business writing. Some basic tenets that one should follow are:

(1) Be brief.
(2) Revise.
(3) Rewrite.

I know this seems overly simplistic but remember one's purpose is to communicate a clear, decisive message and not to prove one's eloquence and mastery of language.

Make more effective presentations

I freely admit that I am not an expert at delivering impactful presentations. In fact, I am not very good at all. However, I want to change that. Perhaps I do not know what are the best things to do, but I can recognize what works and what does not work when I see it. I have sat through too many ineffective presentations (re: boring & long.) During many of these times, I have had to work hard to supress my yawns.

As I have no desire to cure insomnia (via bad presentations), I am diligently trying to improve this skill. Two excellent web sites I have come across are Presentation Zen and Beyond Bullets.

I know now that my PowerPoint slides do not represent the totality of my message. PowerPoint is simply a tool. An easy to misuse tool, but a tool nevertheless.

I can honestly say that I see a huge before and after difference in my own productions. My presentations are more clear, simple, eloquent, effective and engaging. Of course, I'll need some audience feedback to confirm this but I know I am on the right track.

Below are two samples from different presentations that I prepared that attempt to convey the same message.

Originally, I packed lots of information onto my foils (or slides). Some of the problems with this foil are: (1) People read it rather than listen to me. (2) There is too much information. (3) There are multiple thoughts. (4) What is it trying to say? (5) When projected, black text on a white background can be difficult to read. If you are sitting 100 feet away could you even read this foil?

Now, I have broken apart the original slide into many distinct ones. Each has its own purpose and only one message. Much more elegant and simple. Also, it is easy to understand the purpose of the slide. Of course, all other pertinent information from the first foil is maintained; I merely stored it in the foil's notes.

This was my first attempt on what I hope will be one of many.