Tag Archive for: business requirements Page 3

Tag Archive for: business requirements

Managing software projects is difficult under the best circumstances. The project manager must balance competing stakeholder interests against the constraints of limited resources and time, ever-changing technologies, and challenging demands from high-pressure people. Project management is a juggling act, with too many balls in the air at once.

Unfortunately, many new project managers receive little training in how to do the job. Anyone can learn to draw a Gantt chart, but effective project managers also rely on the savvy that comes from experience. Learning survival tips from people who’ve already done their tours of duty in the project management trenches can save you from learning such lessons the hard way.

This three-part series, adapted from my book Practical Project Initiation: A Handbook with Tools (Microsoft Press, 2007), introduces twenty-one valuable practices that can help both rookie and veteran project managers do a better job with less pain. The practices are organized into five categories:

  1. Laying the foundation.
  2. Planning the project.
  3. Estimating the work.
  4. Tracking your progress.
  5. Learning for the future.

When initiating a new project, study this list of practices to see which ones would be valuable contributors to that project. Build the corresponding activities into your thinking and plans. Recognize, though, none of these practices will be silver bullets for your project management problems. Also, remember that even “best” practices are situational. They need to be selectively and thoughtfully applied only where they will add value to the project.

Laying the Foundation

Practice #1: Define project success criteria. At the beginning of the project, make sure the stakeholders share a common understanding of how they’ll determine whether this project is successful. Begin by identifying your stakeholders and their interests and expectations. Next, define some clear and measurable business goals. Some examples are:

  •  Increasing market share by a certain amount by a particular date.
  • Reaching a specified sales volume or revenue.
  • Achieving certain customer satisfaction measures.
  • Saving money by retiring a high-maintenance legacy system.

These business goals should imply specific project success criteria, which again should be measurable and trackable. These goals could include achieving schedule and budget targets, delivering committed functionality that satisfies acceptance tests, complying with industry standards or government regulations, or achieving specific technology milestones. The business objectives define the overarching goal. It doesn’t matter if you deliver to the specification on schedule and budget if those factors don’t clearly align with business success.

Not all of these defined success criteria can be your top priority. You’ll have to make some thoughtful tradeoff decisions to be sure that you satisfy your most important priorities. If you don’t define clear priorities for success, team members can work at cross-purposes. Chapter 4 of Practical Project Initiation presents a tutorial on defining project success criteria.

Practice #2: Identify project drivers, constraints, and degrees of freedom. Every project must balance its functionality, staffing, budget, schedule, and quality objectives. Define each of these five project dimensions as either a constraint within which you must operate, a driver strongly aligned with project success, or a degree of freedom you can adjust within some stated bounds. I explain this idea more fully in my book Creating a Software Engineering Culture (Dorset House, 1996).

I’m afraid I have bad news: not all factors can be constraints, and not all can be drivers. If you are given a defined feature set that must delivered with zero defects by a specific date by a fixed team size working on a fixed budget, you will most likely fail. An over constrained project leaves the project manager with no way to deal with requirement changes, staff turnover or illness, risks that materialize, or any other unexpected occurrences.

I once heard a senior manager and a project leader debate how long it would take to deliver a planned new large software system. The project leader’s top-of-the-head guess was four times as long as the senior manager’s stated goal of six months. The project leader’s response to the senior manager’s pressure for the much shorter schedule was simply, “Okay.” A better response would have been to negotiate a realistic outcome through a dialogue:

  •  Does something drastic happen if we don’t deliver in six months (schedule is a constraint), or is that just a desirable target date (schedule is a driver)?
  • If the six months is a firm constraint, what subset of the requested functionality do you absolutely need delivered by then? (Features are a degree of freedom.)
  • Can I get more people to work on it? (Staff is a degree of freedom.)
  • Do you care how well it works? (Quality is a degree of freedom.)
  • Can I get more funding to outsource part of the project work? (Cost is a degree of freedom.)

Practice #3: Define product release criteria. Early in the project, decide what criteria will indicate whether the product is ready for release. Some examples of possible release criteria are:

  • There are no open high-priority defects.
  • The number of open defects has decreased for X weeks, and the estimated number of residual defects is acceptable.
  • Performance goals are achieved on all target platforms.
  • Specific required functionality is fully operational.
  • Quantitative reliability goals are satisfied.
  • Specified legal, contractual, or regulatory goals are met.
  • Customer acceptance criteria are satisfied.

Whatever criteria you choose should be realistic, objectively measurable, documented, and aligned with what “quality” means to your customers. Decide early on how you will tell when you’re done, track progress toward your goals, and stick to your guns if confronted with pressure to ship before the product is ready for prime time. See Chapter 5 of Practical Project Initiation for more about defining product release criteria.

Practice #4: Negotiate achievable commitments. Despite pressure to promise the impossible, never make a commitment you know you can’t keep. Engage in good-faith negotiations with customers, managers, and team members to agree on goals that are realistically achievable. Negotiation is required whenever there’s a gap between the schedule or functionality the key project stakeholders demand and your best prediction of the future as embodied in project estimates.

Principled negotiation involves four precepts, as described in Getting to Yes by Roger Fisher, William Ury, and Bruce Patton (Penguin USA, 1991):

  • Separate the people from the problem.
  • Focus on interests, not positions.
  • Invent options for mutual gain.
  • Insist on using objective criteria.

Any data you have from previous projects will strengthen your negotiating position, especially because the person with whom you’re negotiating likely has no data at all. However, there’s no real defense against truly unreasonable people.

Plan to renegotiate commitments when project realities (such as staff, budget, or deadlines) change, unanticipated problems arise, risks materialize, or new requirements are added. No one likes to have to modify his commitments. But if the reality is that the initial commitments won’t be achieved, let’s not pretend that they will right up until the moment of disappointing truth.

Planning the Project

Practice #5: Write a plan. Some people believe the time spent writing a plan could be better spent writing code, but I don’t agree. The hard part isn’t writing the plan. The hard part is doing the planning—thinking, negotiating, balancing, asking, listening, and thinking some more. Actually writing the plan is mostly transcription at that point. The time you spend analyzing what it will take to solve the problem will reduce the number of surprises you encounter later in the project. A useful plan is much more than just a schedule or task list. It also includes:

  • Staff, budget, and other resource estimates and plans.
  • Team roles and responsibilities.
  • How you will acquire and train the necessary staff.
  • Assumptions, dependencies, and risks.
  • Target dates for major deliverables.
  • Identification of the software development life cycle that the project will follow.
  • How you will track and monitor the project.
  • Metrics that you’ll collect and analyze.
  • How you will manage any subcontractor relationships.

Your organization should adopt a standard software project management plan template, which each project can tailor to best suit its needs. You might start with the project management plan template available at www.ProjectInitiation.com. Adjust and shrink this template to suit the nature and size of your own projects.

If you commonly tackle different kinds of projects, such as major new product development projects as well as small enhancements, I suggest you adopt a separate project plan template for each project class. The project plan should be no longer or more elaborate than necessary to make sure you can successfully execute the project. One page might suffice in some cases. But always write a plan.

Practice #6: Decompose tasks to inch-pebble granularity. Inch-pebbles are miniature milestones (get it?). Breaking large tasks into multiple small tasks helps you estimate them more accurately, reveals work activities you might not have thought of otherwise, and permits more accurate, fine-grained status tracking. Select inch-pebbles of a size that you feel you can estimate accurately. I feel most comfortable with inch-pebbles that represent tasks of about five to fifteen labor-hours. Overlooked tasks are a common contributor to schedule slips. Breaking large problems into smaller bits reveals more details about the work that must be done and improves your ability to create accurate estimates. You can track progress based on the number of inch-pebbles that the team has completed at any given time, compared to those you planned to have done by that time.

Part 2 of this series will continue with additional practices for planning the project and several tips for preparing more realistic estimates.

Also read Project Management Best Practices, Part 2
Also read Project Management Best Practices, Part 3

Jama Software has partnered with Karl Wiegers to share licensed content from his books and articles on our web site via a series of blog posts, whitepapers and webinars.  Karl Wiegers is an independent consultant and not an employee of Jama.  He can be reached at http://www.processimpact.com.  Enjoy these free requirements management resources.

High-performance projects have effective processes for all of the requirements engineering components: elicitation, analysis, specification, validation, and management. To facilitate the performance of these processes, every organization needs a collection of appropriate process assets. A process encompasses the actions you take and the deliverables you produce; process assets help the team members perform those processes consistently and effectively. These process assets will help those involved in the project understand the steps they should follow and the work products they’re expected to create.

Table 1 identifies some valuable process assets for requirements engineering. No software process rule book says that you need all of these items, but they will all assist your requirements-related activities. Procedures should be no longer than they need to be to let team members consistently perform the tasks effectively. They need not be separate documents. For instance, an overall requirements management process could include the change control procedure, status tracking procedure, and impact analysis checklist.

Following are brief descriptions of each of these process assets. Many of these are available at http://www.processimpact.com/goodies.shtml. Keep in mind that each project should tailor the organization’s assets to best suit its needs.

Table 1. Key process assets for requirements development and requirements management.

Requirements Development Process Assets

Requirements development process. This process describes how to identify stakeholders, user classes, and product champions in your domain. It should address how to plan the elicitation activities, including selecting appropriate elicitation techniques, identifying participants, and estimating the effort and calendar time required for elicitation. The process describes the various requirements documents and models your project is expected to create and points the reader toward appropriate templates. The requirements development process also should identify the steps the project should perform for requirements analysis and validation.

Requirements allocation procedure. Allocating high-level product requirements to specific subsystems (including people) is necessary when developing systems that include both hardware and software components or complex products that contain multiple software subsystems. Allocation takes place after the system-level requirements are specified and the system architecture has been defined. This procedure describes how to perform these allocations to ensure that functionality is assigned to the appropriate components. It also describes how you will trace allocated requirements back to their parent system requirements and to related requirements in other subsystems.

Requirements prioritization procedure. To sensibly reduce scope or to accommodate added requirements within a fixed schedule, we need to know which planned system capabilities have the lowest priority. I’ve developed a spreadsheet tool for prioritization (at http://www.processimpact.com/goodies.shtml) that incorporates the value provided to the customer, the relative technical risk, and the relative cost of implementation for each feature, use case, or functional requirement.

Vision and scope template. Step 1 for managing the dreaded specter of scope creep is to document the project’s scope someplace, so we can judge whether proposed new requirements are in or out of scope. The vision and scope document is a concise, high-level description of the new product’s business requirements. It delineates what’s in and what’s out, thereby providing a reference for making decisions about requirements priorities and changes.

Use-case template. The use-case template provides a standard way to describe tasks that users need to perform with a software system. A use-case definition includes a brief description of the task, descriptions of alternative behaviors and known exceptions that must be handled, and additional information about the task.

Software requirements specification template. The SRS template provides a structured, consistent way to organize the functional and nonfunctional requirements for whatever product you’re building. Consider adopting more than one template to accommodate the different types or sizes of projects your organization undertakes. This can reduce the frustration that arises when a “one size fits all” template or procedure isn’t suitable for your project.

SRS and use-case defect checklists. Formal inspection of requirements documents is a powerful software quality technique. An inspection defect checklist identifies many of the errors commonly found in requirements documents. Use the checklist during the inspection’s preparation stage to focus your attention on common problem areas.

Requirements Management Process Assets

Requirements management process. This process describes the actions a project team takes to deal with changes, distinguish versions of the requirements documentation, track and report on requirements status, and accumulate traceability information. The process should list the attributes to include for each requirement, such as priority, predicted stability, and planned release number. It should also describe the steps required to approve the SRS and establish the requirements baseline.

Change control process. A practical change control process can reduce the chaos inflicted by endless, uncontrolled requirements changes. The change control change process defines the way that a new requirement or a modification to an existing requirement is proposed, communicated, evaluated, and resolved. A problem-tracking tool facilitates change control, but remember that a tool is not a substitute for a process.

Requirements status tracking procedure. Requirements management includes monitoring and reporting the status of each functional requirement. You’ll need to use a database or a commercial requirements management tool to track the status of the many requirements in a large system. This procedure should also describe the reports you can generate to view the status of the collected requirements at any time.

Change control board charter. The change control board (CCB) is the body of stakeholders that decides which proposed requirements changes to approve, which to reject, and in which product release or iteration each approved change will be incorporated. The CCB charter describes the composition, function, and operating procedures of the CCB. It’s worth taking the time to describe how a group of key decision makers will collaborate.

Requirements change impact analysis checklist and template. Estimating the cost and other impacts of a proposed requirement change is a key step in determining whether to approve the change. Impact analysis helps the CCB make smart decisions. An impact analysis checklist helps you contemplate the possible tasks, side effects, and risks associated with implementing a specific requirement change. An accompanying worksheet provides a simple way to estimate the labor for the tasks.

Requirements traceability matrix template. The requirements traceability matrix lists all the functional requirements, the design components and code modules that address each requirement, and the test cases that verify its correct implementation. The traceability matrix should also identify the parent system requirement, use case, business rule, or other source from which each functional requirement was derived.

Simply passing out a bunch of process documents to your team members is no guarantee of success. Well-meaning improvement leaders sometimes get carried away, creating much more process documentation than they need. Your process materials should be light enough to be unintimidating, practical, and effective—but no lighter.

Jama Software has partnered with Karl Wiegers to share licensed content from his books and articles on our web site via a series of blog posts, whitepapers and webinars.  Karl Wiegers is an independent consultant and not an employee of Jama.  He can be reached at http://www.processimpact.com.  Enjoy these free requirements management resources.

I conclude this three-part series on the customer–development partnership by elaborating on the Requirements Bill of Responsibilities for Software Customers that I presented in part 1.

Responsibility #1: To educate analysts and developers about your business

BAs depend on you to educate them about your business concepts and terminology. The intent is not to transform BAs into domain experts, but to help them understand your problems and objectives. Don’t expect BAs to grasp the nuances and implicit aspects of your business. BAs aren’t likely to be aware of knowledge that you and your peers take for granted. Unstated assumptions about this knowledge can lead to problems later on.

Responsibility #2: To spend the time to provide and clarify requirements

Customers are busy people, and those who are involved in developing requirements are often among the busiest. Nonetheless, you have a responsibility to invest time in workshops, brainstorming sessions, interviews, and other requirements-elicitation activities. Sometimes the BA might think she understands a point you made, only to realize later that she needs further clarification. Please be patient with this iterative approach to developing and refining the requirements. It is the nature of complex human communication and a key to software success. Be tolerant of what might appear to you to be dumb questions, as a good BA asks questions that get you talking and thinking.

Responsibility #3: To be specific and precise about requirements

It is tempting to leave the requirements vague and fuzzy because pinning down details is tedious and time-consuming. At some point during development, though, someone must resolve the ambiguities and imprecisions. You are the best person to make those decisions. Otherwise, you’re relying on the developers to guess correctly.

It’s fine to temporarily include TBD (to be determined) markers in the SRS to indicate that additional research, analysis, or information is needed. Sometimes, though, people use TBD because a specific requirement is difficult to resolve and no one wants to tackle it head-on. Try to clarify the intent of each requirement so the BA can express it accurately in the SRS.

Responsibility #4: To make timely decisions

Just as when a contractor builds a custom home, the BA will ask you to make many choices and decisions. These decisions include resolving inconsistent requests received from multiple customers, choosing between conflicting quality attributes, and evaluating the accuracy of information. Customers who are authorized to make such decisions must do so promptly when asked. The developers often can’t proceed with confidence until you render your decision, so time spent waiting for an answer can delay progress.

Responsibility #5: To respect a developer’s assessment of cost and
feasibility

All software functions have a cost, and developers are in the best position to estimate those costs (although not all developers are skilled estimators). Some features that you want included might not be technically feasible or might be surprisingly expensive to implement. I learned long ago that there is little correlation between how difficult it seems like something ought to be to do in software and how hard it really is to implement. Certain requirements might demand unattainable performance in the operating environment, or they might require access to data that is simply not available to the system. The developer can be the bearer of bad news about feasibility or cost, and you should respect that judgment.

Sometimes you can rewrite requirements in a way that makes them attainable or cheaper. For example, asking for an action to take place “instantaneously” isn’t feasible, but “within 50 milliseconds” might be achievable.

Responsibility #6: To set requirement priorities

Few projects have the time and resources to implement every desirable bit of functionality. Determining which capabilities are essential, which are useful, and which ones the customers can live without is an important part of requirements development. You have a lead role in setting those priorities, because developers can’t determine how important every requirement is to the customers. Developers should provide information about the cost and technical risk of each requirement to help determine final priorities. When you establish priorities, you help ensure that developers deliver the maximum value at the lowest cost and at the right time.

No one likes to hear that something he wants can’t be completed within the project bounds, but that’s just a reality. The project’s decision-makers will have to elect whether to reduce project scope based on priorities or to extend the schedule, provide additional funds or people, or compromise on quality.

Responsibility #7: To review requirements documents and evaluate prototypes

Peer reviews of requirements are among the most valuable software quality activities. Having customers participate in reviews is the only way to evaluate whether the requirements demonstrate the desired characteristics of being complete, correct, necessary, and so on. A review is also an opportunity for customer representatives to give the BAs feedback about how well their work is meeting the project’s needs. If you aren’t confident that the documented requirements are accurate, tell the people responsible as early as possible and provide suggestions for improvement.

Responsibility #8: To promptly communicate changes to the requirements

Continually changing requirements pose a serious risk to the development team’s ability to deliver a high-quality product on schedule. Change is inevitable and often beneficial, but the later in the development cycle a change is introduced, the greater its impact. Changes can cause expensive rework and schedules can slip if new functionality is demanded after construction is well under way. Notify the BA with whom you are working as soon as you become aware that you need to change the requirements. Incremental development approaches make it easier to incorporate changes during development than trying to perfect the requirements and cast them in concrete early on.

Responsibility #9: To follow the development organization’s change process

To minimize the negative impact of change, follow the project’s defined change control process. This ensures that requested changes are not lost, the impact of each requested change is analyzed, and all proposed changes are considered in a consistent way. As a result, the business stakeholders can make sound business decisions to incorporate certain changes at the right time.

Responsibility #10: To respect the requirements engineering processes the analysts use

Gathering and validating requirements are among the greatest challenges in software development. There is a rationale behind the approaches that the BAs use. Although you might become frustrated with the requirements activities, the time spent developing the requirements is an excellent investment. The process will be less painful if you understand and respect the techniques the BAs use for requirements development. Feel free to ask BAs to explain why they are requesting certain information or asking you to participate in some requirements-related activity.

To apply the ideas I’ve presented in this series of articles, I suggest that BAs and key customers discuss the Bill of Rights to learn whether the customers feel they are not receiving any of their rights. Discuss the Bill of Responsibilities to reach agreement as to which responsibilities the customers will accept. Modify the Bill of Rights and Bill of Responsibilities as appropriate so that all parties agree on how they will contribute to a collaborative working relationship. You’ll be glad you did.

Also read The Customer-Development Partnership, Part 1

Also read The Customer-Development Partnership, Part 2

Jama Software has partnered with Karl Wiegers to share licensed content from his books and articles on our web site via a series of blog posts, whitepapers and webinars.  Karl Wiegers is an independent consultant and not an employee of Jama.  He can be reached at http://www.processimpact.com.  Enjoy these free requirements management resources.

 

The Customer–Development Partnership, Part 2

The first article in this three-part series proposed a Requirements Bill of Rights for Software Customers. In this article, I elaborate on the implications of these rights. In my experience, people who collaborate on project activities rarely take the time up front to discuss the nature of that collaboration. They don’t lay the groundwork for success by exploring just how they can work together effectively toward a common goal. Discussing these rights—or rights like them that better fit your environment—can go a long way toward forging that teamwork. The “you” in each of these rights is the user.

Right #1: To expect analysts to speak your language

Requirements discussions should center on your business needs, tasks, and objectives, using your business vocabulary, which you might have to convey to the business analyst through a glossary. You shouldn’t have to wade through indecipherable computer jargon when talking with a BA.

Right #2: To have analysts learn about your business and objectives

By interacting with users while eliciting requirements, the BAs can better understand your business tasks and how the product fits into your world. This will help developers design a system that satisfies your expectations. Consider inviting developers and BAs to observe what you and your colleagues do on the job. If the system being built is replacing an existing application, the BAs or developers should use the current system as you use it. This will help them see how the current application fits into your work flow and where it can be improved.

Right #3: To expect analysts to write a software requirements specification

The BA will sort through all the information that you and other customers provide to distinguish use cases from business requirements, business rules, functional requirements, quality goals, solution ideas, and other information. The ultimate deliverable from this analysis is a software requirements specification (SRS), which is the detailed agreement between developers and customers on the functions, qualities, and constraints of the product to be built. The SRS might be a single document created early in the project. Alternatively, it might take the form of a series of smaller documents (or other representations) that are created incrementally during the project’s life.

The SRS should be organized and written in a way that you can understand. Your review of these written specifications helps to ensure that they accurately and completely represent your requirements. However, the SRS is not a substitute for ongoing verbal communication among the users, BAs, developers, and other project stakeholders.

Right #4: To receive explanations of requirements work products

The BA might represent the requirements using various diagrams—analysis models—that complement the textual SRS. These alternative views of the requirements are valuable because sometimes graphics are a clearer medium for expressing some aspects of system behavior, such as work flow. Diagrams typically also represent information at a higher level of abstraction than does a detailed specification. This allows you to step back from the trees and get the big picture of the forest as a whole. Although these diagrams might be unfamiliar, the notations used aren’t difficult to understand. Ask the BA to explain the purpose of each diagram and other requirements development work product, what the notations mean, and how to examine the diagrams for errors.

Right #5: To expect analysts and developers to treat you with respect

Requirements discussions can be frustrating if customers and developers don’t understand each other. Working together can open the eyes of both groups to the problems faced by the other. Customers who participate in the requirements development process have the right to expect BAs and developers to treat them with respect and to appreciate the time you’re investing in project success. Similarly, you and your fellow users should demonstrate respect for the development team members as they collaborate with you toward your mutual objective of a successful project.

Right #6: To hear ideas and alternatives for requirements and their implementation

BAs should explore ways that your existing systems don’t fit well with your business processes to make sure the new system doesn’t automate ineffective or obsolete processes. BAs who thoroughly understand the business domain can sometimes suggest improvements in your business processes. A creative BA also adds value by proposing ways that new software could provide capabilities that customers haven’t even envisioned.

Right #7: To describe characteristics that make the product easy to use

You can expect BAs to ask you about characteristics of the software that go beyond the user’s functional needs. These characteristics—quality attributes—make the software easier or more pleasant to use, which lets users accomplish their tasks more efficiently. Users sometimes request that the product be “user-friendly” or “robust” or “efficient,” but such terms are too vague and subjective to help the developers. Instead, the BAs should inquire about specific characteristics that mean user-friendly, robust, or efficient to you.

Right #8: To be given opportunities to adjust requirements to permit reuse

Requirements are often flexible. The BA might know of existing software components that come close to addressing some need you described. In such a case, the BA should give you the option of modifying your requirements so the developers can reuse some existing software. Adjusting your requirements when sensible reuse opportunities are available can save time and money. Some requirements flexibility is essential if you want to incorporate commercial off-the-shelf components into your product, as they will rarely have precisely the characteristics you desire.

Right #9: To receive good-faith estimates of the costs of changes

People make different choices in life when they know that one alternative is more expensive than another is. Estimates of the impact and cost of a proposed change in the requirements help stakeholders make good business decisions about which requested changes to approve. You have the right to expect developers to present realistic estimates of impact, cost, and trade-offs. Developers must not inflate the estimated cost of a change just because they don’t want to implement it. Remember, though, that estimates are not precise predictions of the future, but rather our best forecast based on our experience and the information available at any given time.

Right #10: To receive a system that meets your functional and quality needs

Every stakeholder should share a desire for this project outcome. It can happen only if you clearly communicate all the information that will let developers build the right product and if developers clearly communicate options and constraints. Be sure to state any assumptions or expectations that have not been explicitly discussed. Otherwise, the developers probably can’t address them to your satisfaction.

Also read The Customer-Development Partnership, Part 1

Also read The Customer-Development Partnership, Part 3

Jama Software has partnered with Karl Wiegers to share licensed content from his books and articles on our web site via a series of blog posts, whitepapers and webinars.  Karl Wiegers is an independent consultant and not an employee of Jama.  He can be reached at http://www.processimpact.com.  Enjoy these free requirements management resources.

 

The first article in this two-part series suggested some specific metrics that can help any software-developing organization better understand how it operates and the results it gets. This article will present some suggestions for creating a healthy measurement culture in the organization and give you several practical tips for metrics success.

Creating a Measurement Culture

A software practitioner’s first reaction to a new metrics program often is fear. People are afraid the data will be used against them, that it will take too much time to collect and analyze the data, or that the team will fixate on getting the numbers “right” rather than on building good software. Creating a healthy software measurement culture and overcoming such resistance will take diligent, congruent steering by managers who are committed to measurement and sensitive to these concerns.

To help you overcome the fear, educate our team about the metrics program. Tell them why measurement is important and how you intend to use the data. Make it clear that you will never use metrics data either to punish or reward individuals—and then make sure you don’t. A competent software manager does not need metrics data from individuals to distinguish the effective team contributors from those who are struggling.

It’s also important to respect the privacy of the data. It’s harder to misuse data if managers don’t know who the data came from. Classify each base measure you collect into one of these three privacy levels:

• Individual: Only the individual who collected the data about his own work knows it is his data, although it may be pooled with data from other individuals to provide an overall project profile.

• Project Team: Data is private to the members of the project team, although it may be pooled with data from other projects to provide an overall organizational profile.

• Organization: Data may be shared throughout the organization.

As an example, if you’re collecting work effort distribution data, the number of hours each individual spends working on every development or maintenance phase activity in a week is private to that individual. The total distribution of hours from all team members is private to the project team, and the distribution across all projects is public to everyone in the organization. View and present the data items that are private to individuals only in the aggregate or as averages over the group.

Make It a Habit

Software measurement need not consume a great deal of time. Commercial tools are available for measuring code size in many programming languages. Activities such as daily time tracking of project work constitute a habit each developer gets into, not a burden. Commercial problem tracking tools facilitate counting defects and tracking their status, but this requires the discipline to report all identified defects and to manage them with the tool. Develop simple tracking forms, scripts, and reporting tools to reduce the overhead of collecting and reporting the data. Use spreadsheets and charts to track and report on the accumulated data at regular intervals.

Tips for Metrics Success

Despite the challenges, many software organizations routinely measure aspects of their work. If you wish to join this club, keep the following tips in mind.

Start Small. Because developing your measurement culture and infrastructure will take time, consider using the Goal-Question-Metric method described in the first article in this series to select a basic set of initial metrics. Once your team becomes used to the idea of measurement and you’ve established some momentum, you can introduce new metrics that will provide the additional information you need to manage your projects and organization effectively.

A risk with any metrics activity is dysfunctional measurement, in which participants alter their behavior to optimize something that is being measured instead of focusing on the real organizational goal. As an illustration, if you’re measuring productivity but not quality, expect some developers to change their programming style to visually expand the volume of code they produce, or to code quickly without regard for defects. I can write code very fast if it doesn’t have to run correctly. The balanced set of measurements helps prevent dysfunctional behavior by monitoring the team’s performance in several complementary dimensions that collectively lead to project success.

Explain Why. Be prepared to explain to a skeptical team why you wish to measure the items you choose. They have the right to understand your motivations and why you think the data will be valuable. Be sure to use the data that is collected, rather than letting it rot in the dark recesses of a write-only database. Encourage team members to use the data themselves and to identify other measures that will help them improve their work. When my small software group at Kodak established a work effort metrics program long ago, we found it to be more helpful than we expected. One team member expressed it well: “It was interesting to compare how I really spent my time with how I thought I spent my time and how I was supposed to spend my time.”

Share the Data. Your team will be more motivated to participate in the measurement program if you tell them how you’ve used the data. Share summaries and trends with the team at regular intervals and get them to help you understand what the data is saying. Let team members know whenever you’ve been able to use their data to answer a question, make a prediction, or assist your management efforts.

Define Metrics and Procedures. It’s more difficult and time-consuming to precisely define the base and derived measures than you might think. However, if you don’t pin these definitions down, participants are likely to interpret and apply them in different ways. As a result, you might end up combining apples and oranges, which yields fruit salad instead of meaningful insights. Define what you mean by a “line of code” or a “user story”, spell out which activities go into the various work effort categories, and agree on what a “defect” is. Write clear, succinct procedures for collecting and reporting the measures you select.

Understand Trends. Trends in the data over time are more significant than individual data points. Some trends may be subject to multiple interpretations. Did the number of defects found during system testing decrease because the latest round of testing was ineffective, or did fewer defects slip past development into the testing process? Make sure you understand what the data is telling you, but don’t rationalize your observations away.

Measurement alone will not improve your software performance. Measurement provides information that will help you focus and evaluate your software process improvement efforts. Link your measurement program to your organizational goals and process improvement program. Use the process improvement initiative to choose improvements, use the metrics program to track progress toward your improvement goals, and use your recognition program to reward desired behaviors.

Also Read A Software Metrics Primer, Part 1

Jama Software has partnered with Karl Wiegers to share licensed content from his books and articles on our web site via a series of blog posts, whitepapers and webinars.  Karl Wiegers is an independent consultant and not an employee of Jama.  He can be reached at http://www.processimpact.com.  Enjoy these free requirements management resources.

Customers who request a new or modified information system often do not understand the importance of obtaining input from actual users of the proposed system, in addition to other internal and external stakeholders. Marketing specialists with a great product concept sometimes believe that they can adequately represent the interests of prospective buyers. However, there’s no substitute for gathering requirements directly from the people who will actually use the product.

This article, the first in a three-part series adapted from my book Software Requirements, 2nd Edition, addresses the customer-development relationship that is so critical to software project success. I propose a Requirements Bill of Rights for Software Customers and a corresponding Requirements Bill of Responsibilities for Software Customers. These lists underscore the importance of customer—and specifically user—involvement in requirements development.

Who Is the Customer?

A stakeholder is anyone who works on, is affected by, or can influence the outcome of a project. A customer is an individual or organization who derives either direct or indirect benefit from a product. Software customers include those stakeholders who request, pay for, select, specify, use, or receive the output generated by a software product. Other project stakeholders include business analysts, developers, testers, documentation writers, project managers, support staff, certifying bodies, legal staff, and marketing.

Customers at the senior management or funding sponsor level are responsible for specifying the business requirements. They provide the high-level concept for the product and the business rationale for launching the project. Business requirements describe the business objectives that the customer, company, or other stakeholders want to achieve. Business requirements establish a guiding framework for the rest of the project, and all other product features and requirements should align with satisfying them. However, business requirements do not provide sufficient detail to tell developers what to build.

The next level of requirements—user requirements—should come from people who will actually use the product, either hands-on or indirectly. These users therefore constitute another class of customer. Users can describe the tasks they need to perform with the product and the quality characteristics they expect the product to exhibit.

Customers who provide the business requirements sometimes purport to speak for the users, but usually they are too far removed from the actual user work to provide accurate user requirements. For information systems, contract, or custom application development, business requirements should come from the person with the money, while user requirements should come from the person who will press the keys and move the mouse. The various stakeholders must ensure alignment between the user and business requirements.

Unfortunately, both kinds of customers might not believe that they have the time to work with the requirements analysts who gather, analyze, and document the requirements. Sometimes customers expect the analysts or developers to figure out what users need without a lot of discussion. If only it were that easy. The days of sliding some vague requirements and a series of pizzas under the door to the programming department are long past.

The situation is somewhat different for commercial (shrink-wrap) software development, where the customer and user often are the same person. Customer surrogates, such as the marketing department or product management, might attempt to determine what customers would find appealing. Even for commercial software, though, you should engage end users in the process of developing user requirements, perhaps through focus groups or other engagement techniques. If you do not, be prepared to read magazine reviews that describe shortcomings in your product that adequate user input could have helped you avoid.

Structuring the Partnership

Excellent software products are the result of a well-executed design based on excellent requirements. High-quality requirements result from effective communication and collaboration between developers and customers—a partnership. Too often, the relationship between development and customers becomes adversarial. Managers who override user-supplied requirements to suit their own agenda can also generate friction. No one benefits in these situations.

A collaborative effort can work only when all parties involved know what they need to be successful and when they understand and respect what their collaborators need to be successful. As project pressures rise, it’s easy to forget that all stakeholders share a common objective: to build a successful software product that provides adequate business value and rewards to all stakeholders.

The Requirements Bill of Rights for Software Customers lists ten expectations that customers can legitimately hold regarding their interactions with analysts and developers during the project’s requirements engineering activities. Each of these rights implies a corresponding responsibility on the part of the software developers or analysts. Conversely, the Requirements Bill of Responsibilities for Software Customers lists ten responsibilities that the customer has to the developer during the requirements process. If you prefer, you could phrase these as a developer’s bill of rights.

These rights and responsibilities apply directly to customers when the software is being developed for internal corporate use, under contract, or for a known set of major customers. For mass-market product development, the rights and responsibilities are more applicable to customer surrogates, such as the developing organization’s marketing product management staff.

As part of project planning, the customer and development participants should review these two lists and reach a meeting of the minds. Busy customers might prefer not to become involved in requirements engineering (that is, they shy away from Responsibility #2). However, we know that lack of customer involvement greatly increases the risk of building the wrong product. Make sure the key participants in requirements development understand and accept their responsibilities. If you encounter some sticking points, negotiate to reach a clear understanding regarding your responsibilities to each other. This understanding can reduce friction later, when one party expects something that the other is not willing or able to provide.

Part 2 of this series takes a closer look at the ten customer rights when it comes to software requirements, while Part 3 explores the ten customer responsibilities. If these two lists aren’t quite right for your environment, adapt them to be more relevant. Don’t just assume that these various key project stakeholders already know how to collaborate effectively, though.

Requirements Bill of Rights for Software Customers

You have the right to:

  1. Expect analysts to speak your language.
  2. Expect analysts to learn about your business and your objectives for the system.
  3. Expect analysts to structure the information you present during requirements elicitation into a written software requirements specification.
  4. Have analysts explain all work products created from the requirements process.
  5. Expect analysts and developers to treat you with respect and to maintain a collaborative and professional attitude throughout your interactions.
  6. Have analysts and developers provide you with ideas and alternatives both for your requirements and for implementation of the product.
  7. Describe characteristics of the product that will make it easy and enjoyable to use.
  8. Be given opportunities to adjust your requirements to permit reuse of existing software components.
  9. Receive good-faith estimates of the costs, impacts, and trade-offs when you request a change in the requirements.
  10. Receive a system that meets your functional and quality needs, to the extent that those needs have been communicated to the developers and agreed on.

Requirements Bill of Responsibilities for Software Customers

You have the responsibility to:

  1. Educate analysts and developers about your business and define business jargon.
  2. Spend the time that it takes to provide requirements, clarify them, and iteratively flesh them out.
  3. Be specific and precise when providing input about the system’s requirements.
  4. Make timely decisions about requirements when requested to do so.
  5. Respect a developer’s assessment of the cost and feasibility of requirements.
  6. In collaboration with the developers, set priorities for functional requirements, system features, or use cases.
  7. Review requirements documents and evaluate prototypes.
  8. Communicate changes to the requirements as soon as you know about them.
  9. Follow the development organization’s process for requesting requirements changes.
  10. Respect the processes the analysts use for requirements engineering.

Also read The Customer-Development Partnership, Part 2

Also read The Customer-Development Partnership, Part 3

Jama Software has partnered with Karl Wiegers to share licensed content from his books and articles on our web site via a series of blog posts, whitepapers and webinars.  Karl Wiegers is an independent consultant and not an employee of Jama.  He can be reached at http://www.processimpact.com.  Enjoy these free requirements management resources.

 

 

My friend Nicole was a quality manager at a large company recognized for its software process improvement and measurement success. Once I heard her say, “Our latest code inspection only found two major defects, but we expected to find five, so we’re trying to figure out what’s going on.” Few organizations have deep enough insight into their software development process to make such precise statements. Nicole’s organization spent years establishing effective processes, measuring critical aspects of its work, and applying those measurements on well-managed projects that develop high-quality products.

Software measurement is a challenging but essential component of a healthy and highly capable software engineering culture. This two-part series, adapted from my book Practical Project Initiation: A Handbook with Tools (Microsoft Press, 2007), describes some basic software measurement principles and suggests some metrics that can help you understand and improve the way your organization and its projects operate.

Why Measure Software

Software projects are notorious for running over schedule and budget and having quality problems to boot. Software measurement lets you quantify your schedule and budget performance, work effort, product size, product quality, and project status. If you don’t measure your current performance and use the data to improve your future work estimates, those estimates will forever remain guesses. Because today’s current data becomes tomorrow’s historical data, it’s never too late to begin recording key information about your project.

You can’t track project status meaningfully unless you know the actual effort and time spent on each task compared to your plans and the progress you’ve accomplished as a result. You can’t sensibly decide whether your product is stable enough to ship unless you’re tracking the rates at which your team is finding and fixing defects. You can’t assess how well your new development processes are working without some measure of your current performance and a baseline to compare against. Metrics help you better control your software projects and better understand how your organization works.

What to Measure

You can measure many aspects of your software products, projects, and processes. The trick is to select a small, balanced set of metrics that will help your organization track progress toward its goals. The Goal-Question-Metric (GQM) method promoted by Professor Victor Basili of the University of Maryland is an effective technique for selecting appropriate metrics to meet your needs. With GQM, you begin by selecting a few project or organizational goals. State the goals to be as quantitative and measurable as you can. They might include targets such as the following:

  • Reduce maintenance costs by 50% within one year.
  • Improve schedule estimation accuracy to within 10% of actuals.
  • Reduce system testing time by three weeks on the next project.
  • Reduce the time to close a defect by 40% within three months.

For each goal, think of questions you would have to answer to judge whether your team is reaching that goal. If your goal was “reduce maintenance costs by 50% within one year,” these might be some appropriate questions:

  • How much do we spend on maintenance each month?
  • What fraction of our maintenance costs do we spend on each application we support?
  • How much do we currently spend on adaptive maintenance (adapting to a changed environment), perfective maintenance (adding enhancements), and corrective maintenance (fixing defects)?

Finally, identify metrics that will provide answers to each question. Some of these will be simple items you can count directly, such as the total budget spent on maintenance. These are called base measures. Other metrics are derived measures, which are calculated from one or more base measures, often as simple sums or ratios. To answer the final question in the previous list, you must know the hours spent on each of the three maintenance activity types and the total maintenance cost over a period of time.

Note that I expressed several goals in terms of a percentage change from the current level. The first step of a metrics program is to establish a current baseline, so you can track progress against it and toward your goals. I prefer to establish relative improvement goals (“reduce maintenance by 50%”) rather than absolute goals (“reduce maintenance to 20% of total effort”). You can probably reduce maintenance to 20 percent of total organizational effort within a year if you are currently at 30 percent, but not if you spend 80 percent of your effort on maintenance today.

Your balanced metrics set should eventually include items relating to the six basic dimensions of software measurement: size, time, effort, cost, quality, and status. Table 1 suggests some metrics that individual developers, project teams, and development organizations should consider collecting. Some of these metrics relate to products, others to projects, and the remainder to processes. You should track most of these metrics over time. For example, your routine project tracking activities should monitor the percentage of requirements implemented and tested, the number of open and closed defects, and so on. I recommend including the following base measures fairly early in your metrics program:

  1. Product size: Count lines of code, function points, object classes, number of requirements, or GUI elements.
  2. Estimated and actual duration: Count in units of calendar time.
  3. Estimated and actual effort: Count in units of labor hours.
  4. Work effort distribution: Record the time spent in various development and maintenance activities.
  5. Requirements status: Track the number of requirements that are proposed, approved, implemented, verified, deleted, and rejected.
  6. Defects: Track the number, type, severity, and status of defects found by testing, peer reviews, and customers.

Table 1: Appropriate Metrics for Software Developers, Teams, and Organizations

Level Appropriate Metrics
Individual Developers
  1. Work effort distribution
  2. Estimated and actual task duration and effort
  3. Code covered by unit testing
  4. Number and type of defects found by unit testing
  5. Number and type of defects found by peer reviews
Project Teams
  1. Product size
  2. Estimated and actual duration between major milestones
  3. Estimated and actual staffing levels
  4. Number of tasks planned and completed
  5. Work effort distribution
  6. Requirements status
  7. Requirements volatility
  8. Number of defects found by integration and system testing
  9. Number of defects found by peer reviews
  10. Defect status distribution
  11. Percentage of tests passed
  12. Productivity (also called velocity)
Development Organization
  1. Overall project cycle time
  2. Planned and actual schedule performance
  3. Planned and actual budget performance
  4. Schedule and effort estimating accuracy
  5. Released defect levels
  6. Reuse effectiveness

It’s important to remember that even if you conclude that all of the metrics in Table 1 are valuable, you cannot possibly begin a metrics program that encompasses so many dimensions of measurement. It would overwhelm the practitioners, and you’d likely end up with far more data than you’re prepared to analyze and use to steer the organization’s development activities.

The second article in this series will continue with some recommendations about the importance of creating a measurement culture in the organization, as well as presenting five tips for metrics success.

Read A Software Metrics Primer, Part 2.

Jama Software has partnered with Karl Wiegers to share licensed content from his books and articles on our web site via a series of blog posts, whitepapers and webinars.  Karl Wiegers is an independent consultant and not an employee of Jama.  He can be reached at http://www.processimpact.com.  Enjoy these free requirements management resources.

You might have noticed that requirements activities on projects sometimes lead to adversarial relationships. Customers don’t always feel that business analysts have their best interests at heart. Product managers get frustrated when customers demand never-ending changes in requirements but don’t want the delivery date to slip. Testers don’t appreciate having to redo their work because no one told them about updates to the requirements. Developers bristle when the project manager holds their feet to the fire to meet schedule despite piling on new features through scope creep. It’s a wonder anyone still speaks to their colleagues at the end of the project.

If you’re interested in pursuing better requirements processes, you have to respect the many cross-connections between the software development group and numerous external stakeholders. This article identifies some of those important interfaces and suggests ways to engage such stakeholders in a collaborative approach toward more successful projects in the future.

Figure 1. Requirements-related interfaces between software development and other stakeholders.

Figure 1 shows some of the project stakeholders that can interface with a software development group and some of the contributions they make to a project’s requirements engineering activities. Explain to your contact people in each functional area the information and contributions you need from them if the product development effort is to succeed. Agree on the form and content of key communication interfaces between development and other functional areas, such as a system requirements specification or a marketing requirements document. Too often, important project documents are written from the author’s point of view without full consideration of the information that the readers of those documents need.

On the flip side, ask the other organizations what they need from the development group to make their jobs easier. What input about technical feasibility will help marketing plan their product concepts better? What requirements status reports will give management adequate visibility into project progress? What collaboration with system engineering will ensure that system requirements are properly partitioned among software and hardware subsystems? Strive to build collaborative relationships between development and the other stakeholders of the requirements process.

When the software development group changes its requirements processes, the interfaces it presents to other project stakeholder communities also change. People don’t like to be forced out of their comfort zone, so expect some resistance to your proposed requirements process changes. Understand the origin of the resistance so that you can both respect it and defuse it.

Much resistance comes from fear of the unknown. To reduce the fear, communicate your process improvement rationale and intentions to your counterparts in other areas. Explain the benefits that these other groups will realize from the new process. Make sure they understand the pain that projects have experienced in the past because of shortcomings in your current processes. The prospect of eliminating pain is a great motivator for change. When seeking collaboration on process improvement, begin from this viewpoint: “Here are the problems we’ve all experienced. We think that these process changes will help solve those problems. Here’s what we plan to do, this is the help we’ll need from you, and this is how our work will help us both.”

Here are some forms of resistance–both active and passive—that you might encounter:

• A change control process might be viewed as a barrier thrown up by development to make it harder to get changes made. In reality, a change control process is a structure, not a barrier. It permits well-informed people to make good business decisions. The software team is responsible for ensuring that the change process really does work. If new processes don’t yield better results, people will find ways to work around them—and they probably should.

• Some developers view writing and reviewing requirements documents as bureaucratic time-wasters that prevent them from doing their “real” work of writing code. If you can explain the high cost of continually rewriting the code while the team tries to figure out what the system should do, developers and managers will better appreciate the need for good requirements.

• If customer-support costs aren’t linked to the development process, the development team might not be motivated to change how they work because they don’t suffer the consequences of poor product quality.

• If one objective of improved requirements processes is to reduce support costs by creating higher-quality products, the support manager might feel threatened. Who wants to see his empire shrink?

• Busy customers sometimes claim that they don’t have time to spend working on the requirements. Remind them of earlier projects that delivered unsatisfactory systems and the high cost of responding to customer input after delivery. You’re going to get the customer input eventually. It’s a lot cheaper and less painful (and people are in a better mood) to get it earlier rather than later.

Anytime people are asked to change the way they work, the natural reaction is to ask, “What’s in it for me?” However, process changes don’t always result in fabulous and immediate benefits for every individual involved. A better question—and one that any process improvement leader must be able to answer convincingly—is, “What’s in it for us?” Every process change should offer the prospect of clear benefits to the project team, the development organization, the company, the customer, or the universe. You can often sell these benefits in terms of correcting the known shortcomings of the current ways of working that lead to less than desirable business outcomes.

Jama Software has partnered with Karl Wiegers to share licensed content from his books and articles on our web site via a series of blog posts, whitepapers and webinars.  Karl Wiegers is an independent consultant and not an employee of Jama.  He can be reached at http://www.processimpact.com.  Enjoy these free requirements management resources.

Ambiguity is one of the biggest problems I see with requirements specifications written (as they all are) in natural language. There is no end to ways that people can miscommunicate through the written word. The business analyst’s goal is to try to make the meaning of each requirement as precise and clear as possible, aiming for just one possible interpretation of each. In this final article in the series, I offer some guidelines for writing requirements more precisely to avoid some of the pitfalls of ambiguous language.

Synonyms

I once reviewed some requirements for software that controlled several analytical chemistry instruments in a laboratory. In some places, the analyst who wrote the specification referred to “chemical samples,” and in other places she referred to “runs.” I asked her about the difference between a sample and a run. “They’re really the same thing,” she replied. I suggested she pick one term and stick to her story. Whenever I read a document that uses slightly different terms to refer to the same item, I have to check with someone to ascertain whether they are truly synonyms. Place such definitions in a shared glossary so that team members can use them consistently throughout the project and perhaps even across multiple projects.

Elsewhere in that same SRS the author had used three terms that I thought might be synonyms. When I inquired, I learned that they had subtly different meanings. Define such terms in your project glossary to ensure that all readers can reach the same understanding of the terms.

Pronouns

My mother is a known pronoun abuser. She will say something like, “He said he’d bring that down as soon as he was done with it,” and I’ll have no idea who or what she is talking about. Pronouns also can be a source of confusion in a requirements specification. Be certain that the antecedent is crystal clear whenever you employ a pronoun. If you use a word such as this or that, there should be no confusion in the reader’s mind about what you’re referring to.

The abbreviations i.e. and e.g.

Another ambiguity risk involves using abbreviations that some readers might misconstrue. A common point of confusion is the use of i.e.  versus e.g. Consider the following requirement from an actual specification:

The program needs to have a means of allowing the operator to manually activate certain portions of the process in the event a mistake is made (i.e., activate the valve set to apply pressure or vacuum, set pressures, and activate the temperature chamber).

The abbreviation i.e. stands for the Latin phrase id est, which means “that is.” The abbreviation e.g. stands for the Latin phrase exempli gratia, which means “for example.” These two abbreviations are so commonly confused that I don’t trust their use in a requirements specification unless I’m positive that the author understands the difference. In the previous example, the use of i.e. indicates that the following list itemizes all portions of the process that require a means of manual activation. However, if the author really meant for these to be just examples—a portion of that set—he should have used e.g. instead. That way, the reader knows that many more such manual activations could be needed. Unfortunately, the reader won’t have any idea how many more activations might be needed or just what those activations are from this requirement. It’s essential to make it clear whether you are presenting a complete list of items or just an illustrative subset. I suggest explicitly saying for example instead of e.g. so every reader knows what you mean.

A/B

Some specification writers use an A/B writing construct, as in the following example:

Prior to operator intervention, a snapshot of this data should be recorded in an audit/history table.

What exactly does this mean? Is this requirement referring to an audit table, a history table, a history of audits, or an audit of histories? Are both kinds of information stored in the same table, or are audits the same as histories, or what? Other than and/or, read/write, and a few others, the A/B construct is rarely used in formal writing because it is so ambiguous. When I see that construct, I can think of five possible interpretations, but I don’t know which one is correct in a given situation:

  • A is the same as B. (If A and B are synonyms, use just one term consistently.)
  • Both A and B. (Use the explicit conjunction and.)
  • A or B. (Use the explicit conjunction or.)
  • A is the opposite of B, as in “approving/disapproving changes.” (Use the conjunctions and and or as appropriate to convey the correct meaning.)
  • “I’m not sure just what I’m thinking here, so I’ll leave it up to each reader to decide what he thinks this means.” (Decide exactly what you intend to say, and choose the right words.)

Similar-Sounding Words

Writers sometimes write one word but mean another. As an illustration, I often hear people say, “I’ll flush out that specification some more,” when they really mean, “I’ll flesh out that specification some more.” Hunters flush their prey from their hiding places, but analysts flesh out their requirements to give them more substance. And consider the following example, drawn from an actual SRS for a telephony product:

Special Day caller tunes (default) will take priority over all configured individual caller settings that a customer has selected. However, if an individual has been assigned a Special Day caller tune for the same date, this will overwrite the Special Day caller tune.

You overwrite a piece of data, but you override a default value. In this context, either interpretation is potentially correct, so it’s imperative that the author chooses the right word. Watch out for these common types of errors, which sometimes arise from mispronunciations in speech. Keep a dictionary handy so that you can be sure which word to use. A useful reference for common word usage errors in English is provided by Paul Brians at http://www.wsu.edu/~brians/errors/errors.html.

Adverbs

Words that end in -ly often are ambiguous. They might describe some desirable property of the product, but exactly what is desired is left to each reader’s interpretation. Here are some real examples of ineffective adverb usage in requirements specifications:

  • Provide a reasonably predictable end-user experience.
  • Offer significantly better download times.
  • Optimize upload and download to perform quickly.
  • Performance for these users should broadly match those for…
  • Downloading this file should complete in approximately 15 minutes.
  • Exposing information appropriately…
  • Allows the user to edit his interests and possibly search results…
  • Request formats sent by customers must be clearly defined.
  • Subscribers who are changing content selection (effectively a subset of the currently subscribed subscribers)…
  • Generally incurs a “per unit” cost…
  • To enable remedial action to be initiated in a timely manner…
  • …as expediently as possible…
  • Occasionally (not very frequently) there will be an error condition…

Some other adverbs to use with caution are directly, easily, frequently, ideally, instantaneously, normally, optionally, periodically, preferably, rapidly, transparently, typically, and usually. Try to be more specific when describing the intended product characteristics so that all readers will share a common vision of what result they will have when they’re done.

You won’t learn how to write good requirements from reading a book on software requirements engineering or a book on technical writing. You need practice. Write requirements to the best of your ability, and then enlist some of your colleagues to review them. Constructive feedback from reviewers can help anyone become a better writer. In fact, it’s essential. Requirements quality is in the eye of the reader of the requirements, not the author. No matter how fine the author thinks the requirements are, the ultimate arbiters are those who must base their own work on those requirements.

Also read Elements of Requirements Style, Part 1

Also read Elements of Requirements Style, Part 2

Also read Elements of Requirements Style, Part 3

Jama Software has partnered with Karl Wiegers to share licensed content from his books and articles on our web site via a series of blog posts, whitepapers and webinars.  Karl Wiegers is an independent consultant and not an employee of Jama.  He can be reached at http://www.processimpact.com.  Enjoy these free requirements management resources.

One of the most common types of requirements problem is missing information. Either entire requirements could be absent—which are hard to spot, being invisible—or individual requirements are missing information that help make them fully comprehensible. In this article I’ll present some examples of both kinds of problems, along with some recommended solutions.

Omissions

When requirements lack important bits of information, it’s hard for all readers to interpret them in the same way unless they make precisely the same assumptions. For instance, a functional requirement might describe a behavior without identifying the triggering cause that leads to that behavior:

The system shall generate an error report and forward it to the user.

This requirement doesn’t identify the stimulus that leads the system to produce the error report. Another common mistake involves missing descriptions of how possible exceptions should be handled. In the previous example, what should happen if no errors occur during the processing being described? It’s unspecified, thereby leaving it up to the developer to decide what to do. Options include:

  • Do nothing (an assumed default perhaps).
  • Present a “Congratulations! No errors found.” message but do not generate a report.
  • Generate an empty report and forward it to the user.
  • Generate a report stating that no errors were found and forward it to the user.

Perhaps we add the following requirement to address the case in which no errors are encountered:

If parsing is successful, the system shall not generate an error report.

This is another description of the system doing nothing, though, as I discussed under “Negative Requirements” in a earlier article in this series. It would be better to state what the system will do if no error is encountered, even if it is to simply continue the processing.

Another kind of incompleteness occurs when requirements describe system behaviors that involve some type of symmetry. Suppose you’re specifying the functional requirements for a bookmark feature in a Web browser. You might say:

The system shall display the user’s defined bookmarks in a collapsible hierarchical tree structure.

So, the user can collapse the bookmark tree, but what if he wants to expand it again? It’s easy to overlook that sort of symmetrical or reverse operation. To remedy this, either you could add a second requirement stating that the tree can be expanded, or you could alter this requirement to say “…in a collapsible and expandable hierarchical tree structure.”

If you omit the reverse operation, the customer and the BA might assume that the missing portion of the symmetrical requirement is implied. If you request an undo capability, of course you want a redo capability as well, right? But implicit requirements make me nervous. They involve too many assumptions about the knowledge and thought processes that other stakeholders must have to ensure that we all get what we expect in the final product. I know of a organization that developed its own tool for editing and storing source code in a database, with no written requirements. Unfortunately, they forgot to include the ability to print the contents of the database. The team members no doubt assumed that a printing function would be included so didn’t even think to mention it. They didn’t mention it, and they didn’t get it.

Boundaries

Boundary values in numerical ranges provide additional opportunities for creating ambiguity, as well as being places to look for missing requirements. Suppose you’re writing software for a point-of-sale system and you need to comply with a business rule that states, “Only supervisors may issue cash refunds greater than $50.” An analyst might derive several functional requirements from that business rule, such as the following:

  1. If the amount of the cash refund is less than $50, the system shall open the cash register drawer.
  2. If the amount of the cash refund is more than $50 and the user is a supervisor, the system shall open the cash register drawer. If the user is not a supervisor, the system shall display a message: “Call a supervisor for this transaction.”

But what if the amount of the cash refund is exactly $50? Is this a third, unspecified case? Or is it one of the two cases already described? If so, which one? Such ambiguity forces the developer either to make his best guess or to track down someone who can answer the question definitively. This is an example of the BA generating an inconsistency between a higher-level piece of information—the business rule—and the functional requirements derived from it.

You can resolve boundary ambiguities in one of two ways. The previous requirement #1 could be rewritten as, “If the amount of the cash refund is less than or equal to $50, the system shall open the cash register drawer.” This preserves the original intent of the business rule and eliminates the ambiguity.

Alternatively, you could use the words inclusive and exclusive to explicitly indicate whether the endpoints of a numerical range are considered to lie within the range or outside the range. To illustrate with a different example, you might say, “The system shall calculate a 20% discount on orders of 6 to 10 units, inclusive.” This wording makes it perfectly clear that both endpoints of the range, 6 and 10, lie within the range subject to the 20-percent price discount. You still need to review a set of similar requirements to make sure the range endpoints don’t overlap, though. For example, note the inconsistency between the following two requirements:

  1. The system shall calculate a 20% discount on orders of 6 to 10 units, inclusive.
  2. The system shall calculate a 30% discount on orders of 10 to 20 units, inclusive.

The boundary value of 10 is incorrectly included in both ranges. Using a table to show this sort of information is more concise and makes these kinds of errors more evident:

Units Purchased Discount Percentage
1–5 0
6–10 20
11–20 30
21+ 40

Also read Elements of Requirements Style, Part 1

Also read Elements of Requirements Style, Part 2

Also read Elements of Requirements Style, Part 4

Jama Software has partnered with Karl Wiegers to share licensed content from his books and articles on our web site via a series of blog posts, whitepapers and webinars.  Karl Wiegers is an independent consultant and not an employee of Jama.  He can be reached at http://www.processimpact.com.  Enjoy these free requirements management resources.