Requirements: A Primer for Technical Communicators

Home/Publications/Best Practices Newsletter/2004 – Best Practices Newsletter/Requirements: A Primer for Technical Communicators

CIDM

October 2004


Requirements: A Primer for Technical Communicators


CIDMIconNewsletter Karen Steele and Jan Shelton, 7-Eleven, Inc.

Poorly written requirements are the single biggest point of failure in the development of new software systems. Requirements that are not carefully defined or are written in ambiguous terms result in an endless stream of re-working and budget overruns.

Smart project managers these days are trying to solve the problem with the addition of professional communicators to their project teams to both elicit crisp requirements and express them in simple, accessible terms.

Writing requirements is primarily a matter of clarifying, elaborating, and transcribing.

-Weigers, 2000

The difficulty of developing requirements is two-fold: determining the core requirement with its underlying drivers and then expressing that requirement in simple, concise terms that will not be misinterpreted.

Professional communicators, especially technical communicators, are trained to elicit information about systems, the business they support, and the rules and regulations that govern that business. Additionally, professional communicators ably express technical or complex concepts in clear, easy to digest terms-precisely what is needed for stellar requirements gathering and writing.

This point is not lost on experienced project managers who’ve been bitten by the Bad Requirements Bug. In fact, a quick search of the Dallas area job bank for professional communicators finds these skills from recent job postings:

    • Strong interviewing, facilitation, problem resolution, consensus building, and negotiating skills.
    • Ability to assimilate input from many different sources and present concise recommendations.
    • Ability to communicate technical concepts to professional, non-technical clients.

 

This is the type of work in which technical communicators excel. Their function on a requirements gathering team is vital. They pay attention to small linguistic details that other analysts and developers might miss.

The search for good requirements is so critical in development projects that Rational Software (now an IBM subsidiary) has defined managing requirements as a primary component of their Rational Unified Process (RUP).

Errors made during the requirements stage account for 40 to 60 percent of all defects found in a software project.

-Wiegers, 2003

If you’ve ever been involved with a software-development project, chances are you have encountered a project that has gone haywire. What can be done to prevent scenarios like this? It’s an issue project managers have been wrestling with for decades.

The hardest part of building a software system is deciding what precisely to build. No other part of the conceptual work is as difficult as establishing the detailed requirements, including all the interfaces to people, to machines, and to other software systems. No other part of the work so cripples the resulting system if done wrong. No other part is more difficult to rectify later.

-Brooks, 1987

Errors made up front are the easiest to correct if found early. But often, requirements defects are not identified until late in the development cycle.

If a unit cost of one is assigned to the effort required to detect and repair an error during the coding stage, then the cost to detect and repair an error during the requirements stage is between five

[and] ten times less. Furthermore, the cost to detect and repair an error during the maintenance stage is twenty times more.

-Leffingwell, 2003

First, Some Definitions

What are requirements? Some view them as a series of scribbles on a napkin, while others create a “laundry list” of features that may or may not adequately describe what is actually needed. There are many definitions of requirements. Here is one:

A description of a condition or capability of a system; either derived directly from user needs or stated in a contract, standard, specification, or other formally imposed document.

-Krutcheon, 2000

Requirements specify what a system does, not how it does it. To be effective, software requirements must be clear, unambiguous, and written using a concise business vocabulary, not computer jargon. They must be written so that project stakeholders (anyone with a vested interest in the project) can easily understand them. For example, a system intended to scan incoming product at a store may have the following requirement:

The system must allow a store to receive and check in mThe system must allow a store to receive and check in multiple deliveries per day from the same vendor.

This requirement does not specify the menu or button on which the function is to be displayed; it says only that it must allow a store to receive and check in multiple deliveries. Requirements are not lists of features (although features play a pivotal role in the requirements definition process). They do not include design or interface details such as specific menu or button names. Requirements exclude implementation details, procedures, testing, prototypes, project planning information, or anything else that does not precisely define what the system must do or how it must behave.

Levels of Requirements

A quick scan of the literature uncovers a host of requirement categories (see Figure 1). Upon review, it seems that there are as many categories as there are experts. This article addresses the following categories:

  • Business
  • Functional
  • Non-Functional

October04a3

Figure 1. Requirement Categories

Business (also called stakeholder needs)
Business requirements describe the high-level needs, goals, and objectives of the business that the system is intended to fulfill. They are typically defined in a “vision” document or project charter. They describe why the business is building the system. Generally, these are phrased in terms of increasing savings, generating revenue, increasing sales volume, making business processes more efficient, or other business benefits:

The goals for transitioning to the new system include:

  • Improving the timing of invoice processing.
  • Maintaining or reducing labor required to check in stock, extend retail amounts based on invoice quantities, and reconcile the merchandise report.

Closely aligned with the business requirements are system features. These are the bulleted items you see on packages (spell check, automatic downloading of new releases, and so on). Leffingwell (2000) defines a feature as “a service the system provides to fulfill one or more stakeholder needs.” A feature in our store system might be:

The system must allow a store to receive and check in mThe solution must handle the return of broken, damaged, or discontinued products or supplies to the vendor. This capability must include the ability to return only a portion of the vendor’s case quantity (see Figure 2).

Functional
Functional requirements dictate how the system behaves. They “describe the observable behaviors the system will exhibit under specific conditions and the actions the systems will let the users take” (Wieger, 2003). These are statements of behavior, such as, “the in-store main unit and handheld scanner must be usable throughout all interior locations.” These are the types of requirements that compose a use case, which is a collection of specific user goals or business tasks users must perform.

When writing functional requirements, be sure to phrase them in terms of what the system must do, not the people using it. Consider the following functional requirement:

The system must display an accept/reject function that Approvers use to confirm that they have reviewed the updated information and to accept or reject the updates.

A related requirement might be:

Approvers must enter a rejection reason if they reject the changes.

This requirement does not tell us what the system must do; it tells us what the user must do. A slight rephrasing to focus on what the system does will help:

The system must require Approvers to enter a rejection reason if they reject the updates.

October04a8

Figure 2. Relationship Between Business Requirements
(Stakeholder Needs), Features, and Requirements

Non-functional
Non-functional requirements describe attributes of a system rather than behaviors. They include categories such as constraints, external interfaces, business rules, quality attributes, and data definitions.

Constraints
Anything that limits the capabilities of the system or the process used to develop it is a constraint. Typical constraints include physical size (if the system must be able to fit in a small area) or weight (if the system must be handheld). Constraints often limit or interfere with other functional or business requirements. For example, “the system response time must be one second or less” could well be impossible if the projected load on the system is high or the hardware selected cannot support that level. These conflicts must be resolved with all stakeholders before starting development.

Sometimes, stakeholders might define a constraint that is actually a preference. For example, requirements such as “the system must be consistent with the existing AP system” could be an expression of concern about ease of use and the amount of training required. It is the job of the requirement analyst to continue probing to determine the implied requirement.

External Interfaces
Links to legacy systems are a common requirement for systems today. Banking, airline, insurance, and other large-scale systems-development projects likely mandate input to or output from a large mainframe system. Such interfaces may, like constraints, limit design choices. In addition to external systems, other interfaces might include hardware or users.

Business Rules
According to the Business Rules Group (1993), “a business rule is a statement that defines or constrains some aspect of the business. It is intended to assert business structure or to control or influence the behavior of the business.”

Statements that define certain conditions under which a user can log into a system or specify that certain standards must be met are examples of business rules. The following business rules might apply to our store system:

If the Store Staff do not complete the check-in process by 6:00 pm local time, the store will be invoiced based on the ordered quantity.

Product returns are made using the vendor’s delivery unit of measure. Any other unit of measure is handled manually.

Quality Attributes
Quality attributes include usability, safety, security, reliability, supportability, efficiency, availability, maintainability, portability, and performance. You need not worry about defining requirements for each of these quality attributes. In fact, your project may add more or remove some. They serve as a check list during requirements gathering sessions.

For example, a performance requirement might state that: “The system must be able to send a minimum of 4,000 transactions per hour to the host system.” An availability requirement might say, “the system must operate with a 99.7 percent uptime during a normal processing cycle.”

Data Definitions
Data types, formats, default values, value ranges, and the like are data definitions. These should be specified in a separate document or repository, not in the requirements document itself.

Conclusion

Clearly defined, unambiguous requirements provide the project team with a solid base upon which to build the project. They provide a clear set of objectives against which the team can measure their progress. These requirements are also the yardstick against which the customer will measure the effectiveness of the project. Well-defined and -written requirements are so critical to the success of the project that leaving their development in the hands of anyone other than a seasoned communicator could be construed as foolhardy.

Clearly, defining and writing requirements is a critical task that is best performed by a team that includes a seasoned communicator, skilled in both the definition and clear expression of those requirements. CIDMIconNewsletter

About the Authors

Shelton bw scaled23 Steele b-w35

We use cookies to monitor the traffic on this web site in order to provide the best experience possible. By continuing to use this site you are consenting to this practice. | Close