Business Analyses Question

CHAPTER 14 Write the Solution Document

Poor requirements definition is the root cause of bad software.

—Carey Schwaber, Forrester Research

The real work of defining the solution to the business problem is in the elic- itation to gather the information on which to base the analysis and the analy- sis that produces the solution. Writing it down is almost anti-climatic. However, when the documented version of the solution is poorly written, ambiguous, redundant, imprecise, untestable, verbose, and generally un- readable, then all the work done to create the best solution ever is for naught. The solution when implemented will still be wrong.

The heavy lifting has been done at this point. We have a solution that the product stakeholders have determined is good: When we do everything that is stated in the solution, the problem is solved. The solution may exist in an informal format—yellow-lined paper, notes, sketches—and now it is time to convert all of it to the formal, persistent, formatted, official solution document.

The Value of Documentation

Voluminous documentation is part of the problem, not part of the

solution.

—Tom DeMarco, PeopleWare

‘‘We spend a lot of time documenting the system for the developers and then they just do whatever they want. They even go over and talk to the users and create stuff that is not in our documentation.’’

285

Many business analysts feel that their job is about writing documenta- tion and nothing else. It is easy to draw that conclusion. In truth, there is no role of documenter. Documenting findings and results is a part of a business analyst’s other roles. It is the proof that the role has been played. We docu- ment the analysis to show that we have done the analysis. We document the requirements to show we have arrived at a stable solution to the business problem. Documentation is a means for recording completed communica- tion. That is all.

There are two types of documentation—persistent and transitory:

1. Persistent is permanent and remains after the solution is completed. 2. Transitory is for the purpose of providing a temporary written record of

some part of the process. You throw away transitory documentation when it has served its purpose.

Your real work is the elicitation and, especially, the analysis that creates the documentation, not the documents produced. Whatever we write down to assist us with elicitation and analysis—interview notes, diagrams on the whiteboard, user interface screen mock-ups on yellow-lined paper, user sto- ries on index cards, and so forth—is transitory and can be discarded once it has served its purpose.

Persistent documentation has considerable importance in some quarters, as it should. Regulations, external system interfaces, corporate policy, and other extra-project requirements demand written documen- tation. Those persistent written records may constitute a large number of documents that a business analyst may have to produce or at least to endure.

‘‘We seem to be spending all our time writing requirements documentation, like business requirements documents and functional requirements specifications. Then the users or the developers tell us it’s wrong.’’

While a considerable amount of communication in business is done through formal documents, most of your communication should be oral and informal, that way there is no major consequence for getting something wrong—there are no documents to fix or rewrite. The business analyst has to determine how much will be done on a given project with formal artifacts, and how much will be done with informal communication. What considerations would there be in making that decision, besides corporate policy? There are positive and negative reasons for persistent documentation as described in Table 14.1.

286 The Process

When a Persistent Requirements Document Is Not Necessary

There are some instances when a requirements document or business solution is not necessary. Simply specifying what needs to be done is good enough. These include:

& The developer, business analyst, and customer work together consis- tently and in the same team.

& The system or modification is not persistent, such as a one-time-only report or query.

& Everyone involved can remember all of the requirements that comprise the solution document without writing them down in any manner.

& The circumstance is that no one will see anything but results; that is, no inspection or review of interim documents (requirements being considered an interim document).

& There is extremely little likelihood that there will be changes to the delivered product after implementation.

Obligation of Persistent Documentation

Once a document is prepared and submitted, especially after it has been approved, it becomes permanent. Because a document serves to freeze

TABLE 14.1 Persistent Documentation

Why should we document?

What are the concerns with

documenting?

Regulations and legal requirements

such as Sarbanes-Oxley.

Documentation is an attempt to forestall

problems.

Maintain history of product and

project.

It is only a reaction to previous

problems.

Produce a permanent record. To cover one’s posterior (not necessarily

the business analyst’s).

Most people think clearer when

expressing their thoughts in the

permanence of documentation.

Goal becomes creating a document

rather than communicating.

Provide evidence of testing, changes,

auditing, completion of phases

or tasks.

Additional documentation may be an

attempt to slow down change—this

could be purposeful to allow more

time for consideration and evaluation

or it could simply be heel dragging.

Facilitates asynchronous analysis over

long distances and periods of time

Costly to create and maintain.

Write the Solution Document 287

communication at a specific point in time, the useful shelf life of a document is about that of a banana. To keep the document useful, the author or desig- nated person must keep the document up to date. Failing to do so means that the time spent in initially preparing the document is wasted.

The more documents that are prepared to occupy permanent places on the shelf, the more documents the business analyst has to keep up to date. And the more documents there are that refer to the same problem or solu- tion, the more care must be taken to make sure that all the documents refer to the same version. Considering the amount of documentation required in some organizations, it is no wonder a business analyst feels that his primary role is documenter.

To counteract this feeling that your world is made of paper, apply criti- cal evaluation and a certain amount of skepticism to every demand for per- sistent documentation. Do as little of it as you can get away with. Focus on communication rather than documentation.

Ask of each documented item: ‘‘Has this been written down before? Do I need to write it down here? Is it necessary to keep this forever?’’ The rules of requirements specify that the solution document contain no redundancies. Documentation should never be redundant either.

You don’t want to spend more time writing about solving the problem than in actually solving it.

Notice that in Figure 14.1 there is a clear separation between analysis and documenting, and that documenting comes only after analysis has been completed. This does not mean that you do not write anything down while analyzing—quite the contrary. When analysis is complete, you have a defined solution written down in some format that has been confirmed by the appro- priate product stakeholders and perhaps accepted by the solution team.

Problem Domain Solution Domain

Use UseProblem

Vision As Is

Accept Solution

To Be

4. Document the solution in the form of requirements.

R e q u i r e m e n t s

1. Determine the problem and vision.

2. Elicit information to determine the problem domain.

3. Analyze the information to determine optimum solution.

I d e n t i f y

D e l i v e r

FIGURE 14.1 Documenting the Requirements

288 The Process

Now you refine those informal documents that define the solution into a formal solution document based on the standards of the organization or IT department.

The Anatomy of Requirements

‘‘We don’t get good requirements because we don’t know what a good require- ment is.’’

What Are Requirements?

Requirements appear in many forms. There are requirements for the project that guide the product implementation and deployment, technical require- ments that define how the product will be built, and product requirements that specify what the product is and what it will do, among others. The busi- ness analyst is concerned with the latter set of requirements.

The problem and product may need to be defined at different levels of requirements to fully understand the entire problem and resulting solution. There may be a high level of abstraction that is understandable to manage- ment and business owners, a more specific level of detail that describes what the users or stakeholders need to do, and an even more exact set of requirements that relate the technical characteristics of the solution and how the system will support the business in solving the problem.

The product itself has different requirements that enable all parties to understand the various aspects of the product, such as requirements that specify what must be done for the product to function in a way that solves the problem, or requirements that specify the quality expected of the prod- uct by those who will use it to solve the problem.

The official IEEE definition of requirement is:

& A condition or capability needed by a user to solve a problem to achieve an objective.

& A condition or capability that must be met or possessed by a system or system component to satisfy a contract, standard, specification, or other formally imposed documents.

& A documented representation of a condition or capability as in (1) or (2).1

Good and Valid Requirements

The requirements documentation process turns a set of good requirements into a set of valid requirements.

Write the Solution Document 289

Good requirements are those that you and the stakeholders all agree completely and accurately solve the problem or some part of it. Good re- quirements do not have to be formal or structured or formatted. They just have to be written down. They may appear as bulleted lists, sketches of user interface screens on a whiteboard, workflow diagrams written on flip charts, collections of index cards containing user stories, notes on the back of an envelope, and so forth.

Valid requirements are the formalized set of requirements that define the solution to the business problem so that the business, upper-level man- agement, and the solution team all understand it in the same way. The defi- nition that we are using for ‘‘valid’’ is from Webster’s Revised Unabridged Dictionary: ‘‘supported by facts or authority’’ and ‘‘capable of being justified, defended, or supported.’’ The valid requirements meet a set of guidelines and rules, which help reduce ambiguity, keep the requirements focused on the problem and solution, and keep the requirements clear, precise, concise, testable, complete, correct, and traceable.

Let’s walk through an example (see Table 14.2). Suppose the stake- holder makes the following request, ‘‘I want all my accounting reports printed out automatically on the first of each month.’’ There are 25 account- ing reports. Your first cut might be ‘‘The system may print accounting re- ports monthly.’’ This statement is neither good nor valid. It does not reflect what the stakeholder requested, and it is ambiguous.

You revise the statement so that it does reflect what the stakeholder has requested: ‘‘The user may print 25 accounting reports on the first of every month.’’ Your stakeholder confirms this requirement as stating what he has requested. He interprets ‘‘may’’ as ‘‘allow,’’ as in ‘‘the system gives me the ability to print 25 accounting reports.’’ This makes it a good requirement. However, the requirement as stated may not produce the result the stake- holder expected. The word ‘‘may’’ could be misconstrued from ‘‘allowing’’ to

TABLE 14.2 Comparison of Good and Valid Requirements

GOOD VALID

No Yes

No The user may print accounting

reports monthly.

4.1 The system will print 31

reports on a specified day of

the month.

Yes The user may print 25

accounting reports on the

first of each month.

4.1 The system will print 25

reports as specified below

on the first of every month.

4.1.1 Report 1 will be . . .

290 The Process

‘‘making a choice’’ as in, ‘‘The user may print, or the user may display . . . ’’ or ‘‘The user may print 25 reports or 100 reports or 1 report’’ or ‘‘The reports may be printed on the first of every month, or not, or perhaps the 15th of every other month, . . . ’’ The developer, to cover every possible option will create a comprehensive complex report generator allowing the user to select which type of report to print (accounting or other), how many reports to print, the format of the reports, the date and sequence of the reports, and even whether to print or display the report. The stakeholder does get the reports he asked for, but has to spend two hours each month setting up the report generator.

So you revise the requirement to be more valid. ‘‘4.1 The system will print 31 reports as specified below on the 31st of each month.’’ Now the requirement is valid, but it is no longer good. The developer will produce exactly what is specified but the number of reports and the date to print are wrong.

The last revision of the requirement states, ‘‘4.1. On the first of every month, the system will print the following reports . . . ’’

Clearly you do not have to go through all these versions to get to the valid requirements. Typically we get good requirements as a result of our effective elicitation. The issue is making them valid. That starts with writing them at the right level of abstraction, which is discussed next.

Levels of Requirements

One of the common questions and points of confusion I encounter in my travels is in the varying definitions of the many categories of requirements. The levels of requirements show a progression from an abstract or general solution to a more detailed specification. The commonly accepted catego- ries are business requirements, user requirements, and system requirements. The business analyst is typically responsible for the first two levels and many times is involved with the third. This does not mean that you have to create three physically separate documents.

Business Requirements Business requirements are the high-level state- ments of what is necessary to solve the problem and define capabilities the system or process must possess. Business requirements may also define con- ditions that must be met or constraints on the solution.

As shown in Figure 14.2, the source of business requirements is gener- ally upper-level management or entities outside the organization, and each business requirement generates either user requirements or system require- ments or both. Business requirements document the high-level business rules, capabilities, policies, and so forth that the business needs to do or to have done to exist as well as the high-level processes that align with the

Write the Solution Document 291

business strategies to keep the business operational according to its mission. This includes:

& Organizational policies and procedures. & Business rules. & External influences such as laws, regulations, and organizational contracts.

& Competition processes and products. & Organizational culture. & Those interacting directly with the organization such as suppliers, cus- tomers, and vendors.

& The marketplace.

Examples of business requirements taken from real-life requirements:

& The customer will have the ability to check out purchases without the assistance of a check-out clerk.

& Sales tax will be applied to all products except dairy and pharmacy. & The new automated audit form will be used starting with fiscal 2003. & All data entry screens will conform to the corporate user interface standards.

& Charges for uninsured subcontractors will be computed to the third dec- imal point and rounded up.

& Automated checkout lanes will allow payment by cash in addition to credit or debit card.

Business Requirements

Organization Policy

Mission Goals Strategies

Laws, Regulations

External Forces

Competition

MarketplaceCustomers

User Requirements

System Requirements

Ge ne

rat es

Generates

FIGURE 14.2 Business Requirements

292 The Process

User or Stakeholder Requirements This level of requirements is derived di- rectly from what the process workers need to do to satisfy the business re- quirements. The workers require additional or different information or must have it presented in a different way. Workers have approaches to perform- ing their jobs that may differ from the way the system or process currently operates. Their expectations of what the system should be doing and how it should be responding constitute their requirements of the system, whether right or wrong.

We record the users’ preferences, predilections, and prejudices (‘‘I want a pink screen of death’’) in the user requirements. We elicit how they do their jobs and look for the variances based on different users or different circumstances. The user needs are generally internal to our investigation.

Example

Another fanciful example . . . Management of the company noticed that its rate of repeat cus-

tomer sales was down. It asked the business analysts to check out the situation. The business analysts traced some of the problem to the cus- tomer service department. The drop rate (the percentage of callers dis- connecting while on hold) for customer service calls had increased by 26 percent over the past five months, which corresponded to the per- centage drop in repeat customer sales. They further found that the aver- age hold time (length of time a caller is on hold waiting for a connection) for customer service calls exceeded the industry average by over three minutes. Investigating further, the business analysts found that the average length of individual customer service calls had in- creased to a little over seven minutes. The business analysts were still investigating the source of the problem when the customer service manager decided that the evidence showed a direct correlation be- tween the length of customer service calls and the reduction of repeat customer sales. The manager established a new rule in the department: No customer service call can last more than two minutes! He then asked IT to assist him in enforcing this rule.

This is a business requirement: all customer service calls will be completed in two minutes. Written out as a business rule, it reads:

Once a customer service call is initiated, the system will termi- nate a still-active call in two minutes.

Write the Solution Document 293

That is, they may never make it into the solution document. Not all user requests become requirements.

As shown in Figure 14.3, every user requirement is derived from and must be traced back to a business requirement. Every user requirement has at least one corresponding system requirement.

Here are some examples of user requirements:

& I need to see a warning message before I delete any project data to re- mind me what data I am deleting.

& We need to be able to enter up to 30 characters for a person’s title, first and last name.

& The tabs on the screen should be in the following order . . . & I’d like the error message to read ‘‘ . . . ’’ & When the total button is pressed, the check-out screen displays the total of all items scanned.

& When the vendor number is entered, the system will display the vendor name and address.

In the capability maturity model integrated (CMMi), business and user requirements are collectively referred to as customer requirements. In many organizations they generally occupy a single volume, usually called the busi- ness requirements document (BRD), or to increase terminology confusion, a functional requirements specification (FRS), which contains sections for both functional and nonfunctional requirements.

User Requirements

Business Requirements

System Requirements

Generates

Generates

Traces to Users’ Needs

Forms, Documents

Policies Plus Procedures Operations Manuals Training Manuals Etc.

Help Desk Logs

FIGURE 14.3 User Requirements

294 The Process

System Requirements The system requirements define what the system needs to do to satisfy the user or business requirements. For the most part, system requirements are transparent to the users and are rarely voiced by them. System requirements involve named databases, program interactions, hardware and software interfaces, network paths, and so forth.

As a general rule, system requirements are defined by the solution team and do not appear in the solution document created by the business analyst. System requirements generally appear in the technical specifications or de- sign. However, there are instances where the business requirements may provide guidance in the definition of system requirements. For example, the users may request a specific response time or performance characteristic that will have an effect on the system requirements.

In some organizations, the business analyst creates both the business requirements, including the user requirements, and the system

Example

Continuing our fanciful example . . . The business analysts, thwarted in their attempt to define the real

problem, elicit information from the customer service representatives. During the investigation, the business analysts ask what the customer service representatives need to be able to comply with the manager’s new requirement to end all calls within two minutes.

After a litany of complaints about the new policy, the customer service representatives relate that they have no idea how long calls take. What they would like to see is a clock on the screen that starts when a call is initiated and counts down from two minutes to zero.

Some prototyping sessions later, the business analysts refine the clock graphic to turn pink when there are 30 seconds left, and turn red and emit a soft buzz when 15 seconds are left.

These are user requirements—what the users need to satisfy the business requirements. The user requirements might read:

When the call is initiated the system displays and activates a two-minute clock.

When active, the two-minute clock displays time in digital format.

When the call has been active for 90 seconds, the system turns the color of the clock to pink, and so on.

Write the Solution Document 295

requirements. In a large U.S. bank, one group of business analysts defines the business requirements, and another separate group of business analysts defines the system requirements.

As shown in Figure 14.4, additional information is elicited which creates system requirements, such as design trade-offs and platform considerations. Every system requirement must trace back to either a business requirement or a user requirement.

System requirements define the internal system description. Examples of system requirements are:

& 95 percent of all terminal-initiated activities shall receive a response in 1.5 seconds or less.

& The system must be capable of processing 1,200 transactions in four seconds or less.

& The system must be capable of maintaining terminal response require- ments while simultaneously processing up to eight background regions.

& Response time for worst-case latency will be less than 100 milliseconds.

A top-down structured approach in solution development starts with the high-level business requirements and works downward through the user or stakeholder requirements to the system requirements, which define the details for the developers. More agile and iterative approaches focus on a single function that may be a business requirement, a stakeholder require- ment, a user story, or a use case. There is no concept of, or need for, levels of requirements. The business analyst or product owner, however, may use the levels as a way to organize or prioritize various functions of the overall solution. Looking at the requirements in terms of levels of abstraction also

System Requirements

User Requirements

Business Requirements

Trace to

Technological Limitations and Constraints

Nonfunctional Requirements

Platform Considerations

Design Trade-Offs

Other System and Database Interfaces

Tra ce

to

FIGURE 14.4 System Requirements

296 The Process

helps us to remember that the product stakeholders and solution team natu- rally look at the same problem and solution in different levels of abstraction. Trying to force everyone to see the problem and solution the same way might cause a lot of confusion and frustration. It’s easier to communicate when doing so at the appropriate level of abstraction for the audience.

Requirements Aspects

In addition to different levels, requirements also come in different flavors: functional and nonfunctional. At one time in the checkered history of re- quirements definition only functional requirements were necessary. Non- functional requirements were not a consideration. We did not ask the

Example

The continuing fanciful example . . . The customer service manager signs off on the requirements docu-

ment and the business analysts turn the document over to the solution team. The systems analysts attack the problem. To put the clock on the screen for the customer service representatives, the systems analysts re- alize they need a way of synchronizing the initiation of the call with the clock and decide to use network time protocol (NTP) that requires NTP clients on each customer service representatives’ station and an NTP server on the network. They also specify a faster refresh rate to display the customer service information on the screens to aid in completion of calls in two minutes. This requires upgrading the database management system and increasing the backbone network to 10 gigabytes.

These are all system requirements simply because it is unlikely a customer service representative would say, ‘‘Hey, while you are at it I would like to see network time protocol installed.’’ Nor would we likely hear the customer service manager say, ‘‘Guys, we got to goose up our backbone to 10 gig to get enough throughput to offset the serialization delays at the routers.’’

The system requirements appearing in the system requirements specification might look like this:

There will be an NTP client on each customer service workstation.

Customer information used by customer service will be accessed via a cross-reference table.

Write the Solution Document 297

product stakeholders about reliability, response time, security, availability, capacity, and so forth because we were defining applications that ran on computers (at that time there was no need for the mainframe distinction since there was just the computer). We could not make the functional appli- cation more secure than the computer or increase the response time for our one application, or make the application more reliable than the IBM 360 or the Univac 1180. However, once processing moved out of the safe confines of the computer and onto networks and then the Internet, we had to start worrying about such matters as portability, scalability, security, maintainabil- ity, and the like. Then when information systems moved out of the purview of a group of specialized, trained operators and into the mainstream of pub- lic use, more issues began to find their way into requirements documents: privacy, usability, auditability, globalization, and so forth. We were forced to distinguish between those requirements that defined what needed to be done—the functional requirements—and those requirements that defined the way in which it was done, namely the quality of the solution—the non- functional requirements.

Functional Requirements Functional requirements capture the intended be- havior of the system, what the user or process worker does with the system. This behavior may be expressed as services, tasks, behaviors, or functions the system must perform. Functional requirements are expressed as positive statements of action, written in the active voice.

Functionality can be defined with use cases or with user stories and are generally easier to describe and measure than nonfunctional requirements. This is because they are generally derived from the users’ descriptions of what they do or need to do.

Nonfunctional Requirements Nonfunctional requirements (NFR) capture the required properties or qualities of the system. They define how well some behavioral or structural aspect of the system should be accomplished. There are two types of nonfunctional requirements: those that are observable at runtime (for example, performance, security, reliability, user interfaces, and so on), and those that are not observable at runtime (such as extensibility, portability, reusability). IEEE standard 1233 (1998) lists the nonfunctional re- quirement categories. This list is in Appendix F.

Pay special attention to the definition of nonfunctional requirements be- cause even when they are not explicitly stated, the expectation is that they will be met. It is difficult to elicit nonfunctional requirement information from the process workers and stakeholders (see the Example sidebar). The users are not likely to mention a particular area of concern, especially when they are involved with creating use cases of the system’s functionality. Most of the nonfunctional requirements deal with backend or internal aspects,

298 The Process

such as privacy, security, and data integrity, which are characteristics the us- ers generally do not think about. More likely, the users of a computer system assume that you know that response time has to be fast, the system should be available when they need it, that there should be enough capacity to store accessible data for a period of time, and so forth. However, leave one of those capabilities out—for example, response time—and the system, as a whole, will be considered a failure even when it performs required function- ality precisely right.

Nonfunctional requirements can be very user-specific. One user’s opinion of response time is that it is too slow, while another user work- ing on the same process thinks the response time is a bit too fast. Think of the functional requirements as the meat and potatoes of the meal. The nonfunctional requirements are the sauces and condiments that add quality and individuality to the food. It takes extra time and effort to elicit information about the quality aspects of a computer system. Whether you delight the customer or just give them the functional neces- sities is what creates a quality solution.

Example

It is hard to define . . . NFRs are harder for the process worker to define. I have had heard

process workers say ‘‘I don’t know, but I’ll know it when I see it.’’ One fellow, many years ago, sat at the keyboard to try the user interface for the first time and proclaimed, ‘‘It just does not feel right.’’ No amount of probing could get a clear definition of what it was that did not feel right. I thought maybe we should put padding on the keys of the keyboard to make it feel better.

In one Ohio company, a business analyst described a software de- velopment project that delivered a functionally correct system. It did exactly what the users requested, and yet the users were not happy with it. User management claimed it lacked quality. One user group said they would not use it even if it did match the requirements; they finally signed off even though it did not feel right and took too much time. There were no specifications in the requirements that addressed these issues, and the response time and other performance measure- ments showed that the system worked at the same speed as the other systems the users dealt with. The users could not define what the issues were in unambiguous terms or why they felt it took too much time.

Write the Solution Document 299

Forms of Solution Documentation

The format of the solution might be a formal document such as the business functional requirements (BFR), or the business area requirements (BAR), or the functional requirements document (FRD), or the business solution document (BSD) or any other prescribed format. However, the solution document may be:

& A deck of user stories on index cards. & A set of use case models. & A series of storyboards depicting the system flow. & A set of wire diagrams showing what the Web pages are going to look like. & A prototype of the software functionality, some words and sketches on a whiteboard.

& A requirements stack for use by a scrum team to define its sprints. & Requirements as feature lists maintained on an electronic whiteboard. & A set of loose-leaf notebooks, such that new requirements could be added to the notebooks when the changes were completed.

& A series of test cases.

Regardless of the medium and the message contained therein, the solution document must be understandable by both the business community and the solution team. Whatever the format, the requirements are written down and made accessible for review and discussion by all parties to the solution. The set of requirements which comprise the solution document, taken as a whole, con- stitutes the complete and accurate solution to the defined business problem.

To determine the right level of documentation to provide, use the solu- tion team as the guideline. When the team has enough information to de- velop the solution, you have documented to the right level. When there are a lot of questions being asked by the solution team, it may be an indication that you need to add more information to the documented solution. When there are discussions and debate among the solution team over what you wrote, then you have not depicted the solution in as clear and unambiguous fashion as you thought. Make yourself available, agile-style, to the solution team throughout the implementation effort to clarify, explain, and augment the written word of the solution document. Remember that you have already gotten the solution confirmed by the business community. You are now pro- ducing a valid, persistent document for the solution team.

Write the Right Thing

When documenting the requirements there are some considerations to keep in mind. Here are a few of them.

300 The Process

Do No Harm

It is easy to solve a problem for a particular department of the organization while turning a blind eye to the impact that solution might have on other departments and individuals in the organization. After all, you are there to solve a problem for a problem owner. And the problem owner or depart- ment manager does not care about the other departments. When you are an internal business analyst whose primary goal is to increase the value of the organization this is not a tenable situation. Your efforts to increase the value in one area might be subverted by the loss of value elsewhere. Make sure there are no negative impacts outside the problem domain.

Finish the Analysis First

‘‘I think our lead technical architect is a closet English major. He spends all the time correcting our punctuation and grammar. We can’t get him to focus on what’s important. Any ideas?’’

Just as you do not want to come to conclusions until you have all the data, you do not want to formalize the requirements into the final document until the analysis is complete. Committing to paper too early gets you into edit mode, where concern is more for the format or language than for the overall content and the big picture of what is actually being said. Too many passes through the edit stage and the document, while being grammatically correct, no longer says what it was supposed to say. However, when the solution is defined in the end, make sure that it is grammatically correct, spell checked, and punctuated precisely so that the solution team (or any- one else) does not get stuck correcting your writing and not see what you are writing about.

Only Fill the Gap

‘‘How can I streamline what I am writing in the requirements so that it is easier for them to read and assimilate?’’

The solution should only define what must be done to solve the prob- lem and close the gap identified during gap analysis. The solution docu- ment, in whatever form it takes is the last activity in the solution definition process. Creating the persistent solution document any earlier means that a great deal of time is going to be spent formally correcting, updating, adding new requirements, modifying the solution, and so forth, creating endless versions, which then must be initialed by the original approvers. This is not a game to play. Not only is this inconvenient to those approving the

Write the Solution Document 301

document, it also diminishes the business analyst’s image and credibility. There is no business analyst role that equates to documentation maintainer.

Write the Thing Right

‘‘How can I write better requirements?’’

‘‘I write to better understand what I said.’’

—Philippe Krutchen

Think of the solution document as a model of the solution. Include dia- grams, screenshots, pictures, as well as text descriptions. The solution team will use the diagrams more than the words, especially since they are most likely going to render the words into diagrams for development anyway. The business community may relate to a drawing of a screen layout better than to a three-page textual description of the same screen layout.

Tip

Important: Do not let documentation substitute for real communication. A solution document is only one of several techniques the business ana- lyst uses to ensure that a consensus exists among all stakeholders.

Many business analysts get seduced by the necessity to deliver cer- tain documents. Many are actually evaluated based on the documents they produce. They start making the document the primary outcome of their work. They believe that the document is also a way of perpetually assessing the author’s abilities and productivity, so most of their focus and attention goes to perfecting the document in both content and form. Naturally the document contains the results of gathering informa- tion from the stakeholders. However, when the document is the end result of the business analyst’s activities, more time is spent between the business analyst and the document than between the business analyst and the stakeholders. Ironically, focusing on the document tends to re- duce the flow of information.

It is possible to implement a good system without documentation. It is not possible to create perfect documentation and still deliver the solu- tion in a timely manner. The answer is to spend time communicating directly with the users and with the solution team until everyone under- stands what the solution is. Use the documentation simply to record the solution for posterity.

302 The Process

The Audience

The audience for the solution document you are preparing is the solution team. They are the ones who will be using it. Many business analysts assume that the audience is the product stakeholders because they are the ones who confirm and approve. And, yes, the user community needs to be able to un- derstand the document so that they can confirm and approve, but consider this: After the document has been approved and implementation is under way, what do the stakeholders do with the document? The developers tear it apart, read it thoroughly, and use it as their guideline for development, test- ing, and so forth. Once the product stakeholders approve the document they have no further interest in it except perhaps to compare the results at the end.

Write the solution document with the developer in mind. The glossary, for example, should contain business terms rather than the technical ones we might be tempted to include for the business community’s understanding.

Valid Criteria

Valid requirements must meet, as much as possible, the following criteria:

& Unambiguous & Complete & Consistent

Example

If you think that the ultimate audience for your solution document or requirements is the business community, consider the last time you wrote requirements for implementation. After a couple weeks or months, what is the solution team doing with the requirements (or the user stories, or the product backlog)? They are reading them, discussing them, analyzing them, tearing them apart and so forth. What are the product stakeholders who signed off doing with the document? Using it as a doorstop, piling it with a stack of reports from 2001, putting it under the shorter table leg to balance the table in the coffee room, and in gen- eral ignoring it. It’s rare that the requirements even reappear in the busi- ness community at acceptance test time. They don’t care if it matches the requirements, just that the delivered system solves their problem.

Write the Solution Document 303

& Correct & Feasible & Traceable & Measurable and testable & Maintainable

Creating the solution document is the act of rendering the requirements into a format that complies with these criteria.

Well-Formed

Each form of the solution document has its own guidelines. For example, a use case description typically contains the following information:

& Use case identifier & Actors (both primary and supporting) & Preconditions & Post-conditions & Main success scenario & Exception paths & Alternate paths

When you are creating a formal solution document such as a business requirements document (BRD), functional requirements specification (FRS), system requirements specification (SRS), and the like, there is a formula for creating a well-formed functional requirement. Note that this does not apply to nonfunctional requirements.

A typical functional requirement contains the following structure:

& Condition (if, when, while, during, etc.) & Subject & Imperative (will, shall, must, etc.) & Active verb & Object & Rule (optional) & Outcome (optional)

A functional requirement might look like this:

When the vendor number is entered [condition], the system [subject] will [imperative] display [active verb] the vendor name and address on the screen [object] (see Figure 2.1) as long as the vendor is cur- rent [business rule] for visual verification [outcome] (note that the

304 The Process

last two phrases are somewhat of a stretch for purposes of demonstration).

Figure 2.1 in the requirements document contains the details of what the screen looks like.

The same approach is applied when using user stories. The user story typically has this format:

As a [type of user], I want [some particular feature] so that [some benefit is received].

The requirement above might be rendered as the following user story:

As an accounts payable voucher enterer [type of user], I want the vendor name and address displayed when I enter the vendor num- ber [feature] so that I can visually verify I entered the right vendor number [benefit received].

Details of what the screen looks like and where the information is dis- played are worked out between the developer and user.

In the end the important element in writing the solution document is that it is understandable the same way by everyone with an interest in reading it.

Canned Brains

‘‘What is the balance between over-documentation and not enough?’’

Even though you do not want to excessively maintain a solution docu- ment, it does need to be produced. My high school biology teacher, back in the early 1960s, was Gordon McKee. He had been teaching over 20 years when I took his course. He had a four-inch loose-leaf notebook of notes that was always on the lab table in front of him when he taught. He called it his canned brains. He probably could have taught the class from memory after all that time, and clearly knew the subject, yet he still had that note- book, and he actually referred to it from time to time during each day.

The solution document is much like that set of notes. Everyone may un- derstand exactly what is to be done and verbally agree to it. You may have the specifications on the whiteboard and on index cards, making the formal documentation of the solution seem somewhat redundant. You may argue that the time is spent better writing new requirements than in documenting the ones you have already agreed on. However, there is a significant sense

Write the Solution Document 305

of security when the decisions made last week are recorded and the brilliant ideas from a brainstorming session are inscribed in a form that can be revis- ited later. The solution document, regardless of format, is our canned brains, making sure that we are not sitting around in a meeting snapping our fingers in frustration trying to recall a part of our solution that was written on a long lost scrap of paper. As Peter Coffee says ‘‘It’s easier to be smart tomorrow if you remember how you did it yesterday.’’

Requirements Ownership

‘‘We are tasked with testing the results of the development efforts. We are not given much advance warning. Then when we use the requirements as a guideline to what we expect the system to do, it’s all different. The technical team has made changes and we don’t know what the system is supposed to do. How can we test it on behalf of the users if it isn’t what the users asked for anymore?’’

There was tension in the air of the conference room. I had to address a group of business analysts that I worked with for over a year. I had the basics of their process documented that identified changes to be made to their current way of doing things. They were not pleased with having to estimate the time they needed to elicit information and develop the require- ments. They were not happy having to submit their acceptance test cases to quality assurance (QA) for review. Then I said the simple words, ‘‘The busi- ness analysts own the requirements.’’ They actually cheered when I made this statement. All was forgiven. They were willing to go along with the other impositions. ‘‘Own the requirements’’ meant that no one, including project management, could make official changes to the requirements in the baseline except the business analyst who authored the requirements or an- other designated business analyst. Why were they ecstatic about this change, especially since it sounds like more work for the business analysts?

In the old process at this company, the business analysts developed the requirements and got them confirmed and approved by the business. After that, the solution team made changes to the system both legitimately and under the guise that, ‘‘The users will like this approach better,’’ or, in other words, ‘‘We know what the users need better than they do.’’ Project manage- ment also made changes in the best interests of the project. Project manage- ment, in this case, consisted of former technicians who had written the original system that was being maintained. The changes were never cycled back to the business analysts for review or even a FYI. When testing, QA used the requirements that the developers had used. All was good. How- ever, when the users reviewed the results they saw something different than they had specified and approved and they were not pleased. When they

306 The Process

asked the business analysts about the unauthorized changes, the business analysts were broadsided by the complaints, since they were totally unaware of the alterations.

In the new process, the developers and project management can still make changes. The changes cannot be recorded into the requirements by anyone but the business analysts. Therefore, when it comes to testing, QA creates test cases from the baseline requirements. This process forces the solution team to include the business analysts in on the changes, regardless of what the changes are, whenever the changes affect the customer-ap- proved requirements. The business analysts, in turn, notify the business when any changes affect them.

This is the way it should be—the business analyst owns the requirements.

Complete the Process

The process is completed with a solution document that has been approved by whoever needs to approve it.

Get the process workers and system users—the ones who will actually be executing the new process or functions—to confirm that the solution document, or their part of the solution document, will work just fine. Then get the approval from those with the authority to approve. The approval, in whatever form it takes, is an official blessing by the organization for the proj- ect to continue and for the development team to produce and implement the solution. This approval cannot occur until the solution has been confirmed.

In general, after the solution is confirmed and validated, it is approved with at least three signatures: the business analyst who authored the docu- ment, someone in the business unit (usually the problem owner or the exec- utive decision maker), and the person on the solution team to whom the document is delivered. The reasons for the acceptance signatures are:

& Business analyst: This is indeed my work and I stand behind it. & Business owner: I concur that this set of requirements constitutes a com- plete and accurate solution to my problem.

& Solution team recipient: I understand and accept this document and can implement the solution from it.

In more agile approaches, the approval for the work to be done in the next iteration comes from the product owner or authorized representative.

Once approved the product moves into the implementation phase and the solution team produces the product. This is not a relay race, and the

Write the Solution Document 307

business analyst is not simply passing the baton off to the solution team and retiring from the race to stand on the sidelines and cheer. This is the point that the business analyst has turned over the diagnosis of the business prob- lem and the solution to the specialists to implement the cure. The business analyst, much like the internist, has to be involved with the treatments to make sure the diagnosis was correct and there are no adverse reactions along the way. And the business analyst, like the internist, needs to be pres- ent when the specialists come up with a better treatment plan, so that he can take the notice of change back to the patient, or stakeholder. Exactly what does the business analyst do while the solution team is engaged in the im- plementation of the solution? We explore the activities of the business ana- lyst during solution implementation in Part Five.

Note

1. IEEE Standard 610.12, 1990.

308 The Process

PART V

Producing the Product

Every project needs an individual champion . . . to advocate for

the product.

—Dean Leffingwell

Implementing the solution is the final stage in solving the business problem. During this time the business analyst may find their direct involvement in the project is somewhat reduced while the solution team carries out the coding, testing, database developing, architecting, building, purchasing, and other activities.

During the implementation the business analyst continues to perform the roles of facilitator, communicator, and educator to ensure that the goal of solving the problem is not lost while solving it.

Product Champion

The concept of product champion comes from marketing and research and development. The product champion brings organizational resources to bear on both the definition and the development of a product. The product champion drives the product into existence.

Here is a profile of the successful product champion.1

& Knows the product stakeholders—all of them, & Is agnostic and objective about all the problems and issues in the busi- ness community.

309

& Has business experience in the domain. & Can speak intelligently and confidently about the issues. & Is a good facilitator. & Works and plays well with others on all sides of the issues.

What is the function of a product champion?

& Accepts responsibility that the product delivered to the business solves the business problem.

& Enhances the solution team’s ability to produce the product. & Defends the business community’s need to have the product. & Represents the best interests of the customer(s) and the product, steer- ing product development in the right direction.

& Balances the needs of the solution team against the needs of the product.

This description of the product champion sounds like the description of the business analyst we have come to know and love.

‘‘The product champion is the one person who is officially responsible for delivering the product. This person helps the stakeholders and project manager reach a shared vision for a product, and then defines and initiates the product within that vision.’’

2

By adopting the role of product champion, not only will you hold on to the vision of the product and solution so that the solution team does not go astray and build something that is different than expected, you will also re- sist attempts by the business community to change the product along the way to include additional features that are not part of the solution.

Eyes on the Prize

It is an easy thing to lose sight of the problem. IT projects sometimes go on for months and years. There is a lot involved and a lot at stake. Larger, more mission-critical projects are also more political because they affect more of the organization. As a result there may be compromises and diversions and, occasionally, outright sabotage. In addition, there are the normal distrac- tions that occur in any long-term project: diversion of resources to other temporarily higher priority or more immediate problems; changing person- nel on both the project team and the business management teams with the new players having their own vision of the product; changes in the business and the marketplace, and so forth. Each of these distractions and diversions has the effect of potentially altering the project from its intended goal of solving the stated and approved business problem. The project manager,

310 Producing the Product

who is likely more in tune with the politics, will change the direction of the project when so directed as long as the deadline and/or budget are adjusted accordingly. The business analyst, however, must keep focus on the prob- lem that is being solved, and the product that will solve it, even when it appears no one else is doing so.

The business analyst creates a strong and compelling vision of the solu- tion and can ask the right questions of the solution team to gauge whether the project is on track—not on track with budget and schedule, but on track toward the vision that will provide the solution to the business problem. The solution is a collaborative effort of all parties throughout the solution life cycle. The business analyst is the catalyst for the collaboration: acting as the customer-facing member of the solution team and representing the business in the various implementation decisions to be made. The business analyst moves from center stage (defining the problem and the solution) to a sup- porting role (clarifying, verifying, confirming, and assisting); however, the activities of the business analyst are still integral to the successful solution.

Producing the Product 311