CHAPTER 12

CONSTRUCTION

This chapter discusses the activities needed to successfully build an information system: programming, testing and documenting the system. Programming is time consuming and costly, but except in unusual circumstances, it is the simplest for the systems analyst because it is well understood. For this reason, the systems analyst focuses on testing (proving that the system works as designed) and developing documentation.

OBJECTIVES

• Be familiar with the system construction process
• Understand different types of tests and when to use them
• Understand how to develop documentation

CHAPTER OUTLINE

1. Introduction
2. Managing Programming
   1. Assigning Programmers
   2. Coordinating Activities
   3. Managing the Schedule
   4. Cultural Issues
3. Designing Tests
   1. Testing and Object Orientation
   2. Test Planning
   3. Unit Tests
   4. Integration Tests
   5. System Tests
   6. Acceptance Tests
4. Developing Documentation
   1. Types of Documentation
   2. Designing Documentation Structure
   3. Writing Documentation Topics
   4. Identifying Navigation Terms
5. Applying the Concepts at CD Selections
6. Summary

INTRODUCTION

When people first learn about developing information systems, they usually think immediately about writing programs. Programming can be the largest single component of any systems development project in terms of time and cost. However, it also can be the best understood component and therefore—except in rare circumstances—offers the fewest problems of all aspects of system development. When projects fail, it is usually not because the programmers were unable to write the programs, but because the analysis, design, installation, and/or project management were done poorly. In this chapter, we focus on the construction and testing of the software and the documentation.

Construction is the development of all parts of the system, including the software itself, documentation, and new operating procedures. Looking back at Figure 1-18, we see that the Construction phase of the Enhanced Unified Process deals predominantly with the Implementation, Testing, and Configuration and Change Management work-flows. Implementation obviously deals with programming. Programming is often seen as the focal point of systems development. After all, systems development is writing programs. It is the reason we do all the analysis and design. And it's fun. Many beginning programmers see testing and documentation as bothersome afterthoughts. Testing and documentation aren't fun, so they often receive less attention than the creative activity of writing programs.

However, programming and testing are very similar to writing and editing. No professional writer (or student writing an important term paper) would stop after writing the first draft. Rereading, editing, and revising the initial draft into a good paper are the hallmarks of good writing. Likewise, thorough testing is the hallmark of professional software developers. Most professional organizations devote more time and money to testing (and the subsequent revision and retesting) than to writing the programs in the first place.

The reasons are simple economics: Downtime and failures caused by software bugs¹ are extremely expensive. Many large organizations estimate the costs of downtime of critical applications at $50,000 to $200,000 per hour.² One serious bug that causes an hour of downtime can cost more than one year's salary of a programmer—and how often are bugs found and fixed in one hour? Testing is, therefore, a form of insurance. Organizations are willing to spend a lot of time and money to prevent the possibility of major failures after the system is installed.

Therefore, a program is usually not considered finished until the test for that program is passed. For this reason, programming and testing are tightly coupled, and because programming is the primary job of the programmer (not the analyst), testing (not programming) often becomes the focus of the construction stage for the systems analysis team.

The Configuration and Change Management workflow keeps track of the state of the evolving system. The evolving information system comprises a set of artifacts that includes, for example, diagrams, source code, and executables. During the development process, these artifacts are modified. The amount of work, and hence dollars, that goes into the development of the artifacts is substantial. Therefore the artifacts themselves should be handled as any expensive asset would be handled: Access controls must be put into place to safeguard the artifacts from being stolen or destroyed. Because the artifacts are modified on a regular, if not continuous, basis, good version control mechanisms should be established. The traceability of the artifacts back through the various artifacts developed, such as data management layer designs, class diagrams, package diagrams, and use-case diagrams, to the specific requirements is also very important. Without this traceability, we will not know which aspects of a system to modify when—not if—the requirements change.

In this chapter, we discuss three aspects of construction: managing programming, testing, and writing the documentation. Because programming is primarily the job of programmers, not systems analysts, and because this is not a programming book, we devote less time to programming than to testing and documentation. Furthermore, we do not delve into the details of configuration and change management in this chapter (see Chapter 13).³

MANAGING PROGRAMMING

In general, systems analysts do not write programs; programmers write programs. Therefore, the primary task of the systems analysts during programming is… waiting. However, the project manager is usually very busy managing the programming effort by assigning the programmers, coordinating the activities, and managing the programming schedule.⁴

Assigning Programmers

The first step in programming is assigning modules to the programmers. As discussed in Chapter 8, each module (class, object, or method) should be as separate and distinct as possible from the other modules (i.e., cohesion should be maximized and coupling should be minimized). The project manager first groups together classes that are related so that each programmer is working on related classes. These groups of classes are then assigned to programmers. A good place to start is to look at the package diagrams.

One of the rules of systems development is that the more programmers who are involved in a project, the longer the system will take to build. This is because as the size of the programming team increases, the need for coordination increases exponentially, and the more coordination required, the less time programmers can spend actually writing systems. The best size is the smallest possible programming team. When projects are so complex that they require a large team, the best strategy is to try to break the project into a series of smaller parts that can function as independently as possible.

Coordinating Activities

Coordination can be done through both high-tech and low-tech means. The simplest approach is to have a weekly project meeting to discuss any changes to the system that have arisen during the past week—or just any issues that have come up. Regular meetings, even if they are brief, encourage the widespread communication and discussion of issues before they become problems.

Another important way to improve coordination is to create and follow standards that can range from formal rules for naming files, to forms that must be completed when goals are reached, to programming guidelines (see Chapter 2). When a team forms standards and then follows them, the project can be completed faster because task coordination is less complex.

The analysts also must put mechanisms in place to keep the programming effort well organized. Many project teams set up three areas in which programmers can work: a development area, a testing area, and a production area. These areas can be different directories on a server hard disk, different servers, or different physical locations, but the point is that files, data, and programs are separated based on their status of completion. At first, programmers access and build files within the development area and then copy them to the testing area when the programmers are finished. If a program does not pass a test, it is sent back to development. Once all programs are tested and ready to support the new system, they are copied into the production area—the location where the final system will reside.

Keeping files and programs in different places based on completion status helps manage change control, the action of coordinating a system as it changes through construction. Another change control technique is keeping track of which programmer changes which classes and packages by using a program log. The log is merely a form on which programmers sign out classes and packages to write and sign in when they are completed. Both the programming areas and program log help the analysts understand exactly who has worked on what and the system's current status. Without these techniques, files can be put into production without the proper testing (e.g., two programmers can start working on the same class or package at the same time).

If a CASE tool is used during the construction step, it can be very helpful for change control because many CASE tools are set up to track the status of programs and help manage programmers as they work. In most cases, maintaining coordination is not conceptually complex. It just requires a lot of discipline and attention to tracking small details.

Managing the Schedule

The time estimates that were produced during project identification and refined during analysis and design almost always need to be refined as the project progresses during construction because it is virtually impossible to develop an exact assessment of the project's schedule. As we discussed in Chapter 2, a well-done set of time estimates usually has a 10 percent margin of error by the time we reach the construction step. It is critical that the time estimates be revised as construction proceeds. If a program module takes longer to develop than expected, then the prudent response is to move the expected completion date later by the same amount.

One of the most common causes for schedule problems is scope creep. Scope creep occurs when new requirements are added to the project after the system design was finalized. Scope creep can be very expensive because changes made late in system development can require much of the completed system design (and even programs already written) to be redone. Any proposed change during construction must require the approval of the project manager and should only be done after a quick cost–benefit analysis has been done.

Another common cause is the unnoticed day-by-day slippages in the schedule. One package is a day late here; another one is a day late there. Pretty soon these minor delays add up and the project is noticeably behind schedule. Once again, the key to managing the programming effort is to watch these minor slippages carefully and update the schedule accordingly.

Typically, a project manager creates a risk assessment that tracks potential risks along with an evaluation of their likelihood and potential impact. As the construction step moves to a close, the list of risks changes as some items are removed and others surface. The best project managers, however, work hard to keep risks from having an impact on the schedule and costs associated with the project.

Cultural Issues

One of the major issues facing information systems development organizations is the offshoring of the implementation aspects of information systems development. Conflicts caused by different national and organizational cultures are now becoming a real area of concern. With the potential of cloud computing (see Chapter 11) potentially enabling even more outsourcing, the potential of cultural conflict is even greater.

A simple example that can demonstrate cultural differences with regard to student learning is the idea of plagiarism. What exactly does plagiarism really imply? Different cultures have very different views. In some cultures, one of the highest forms of respect is simply to quote an expert. However, in these same cultures, there is no need to reference the expert. The act of quoting the expert itself is the act of respect. In some cases, actually referencing the expert through the use of quotation marks and a footnote may be viewed as an insult to the expert and the reader because it is obvious to the reader that the writer did not expect the reader to recognize the expert's quote. This expectation was either caused by the reader's own ignorance or the expert's lack of reputation. Either way, the writer would be insulting someone through the use of quotation marks and footnotes. These cultures tend to be collectivist in nature (see Chapters 10 and 13). Consequently, since the collective owns all ideas, there is no concept of theft of ideas. However, in the United States, the opposite is true. If a writer does not use quotation marks and footnotes to appropriately give credit to the source of the quote (or paraphrase), then the writer is guilty of theft.⁶ Obviously, in today's global world, plagiarism is not a simple issue.

Another simple example of cultural differences, with regard to student learning, is the idea of students working together to complete homework assignments. Even though we all know that research has shown that students learn better in groups, in the United States, we view students who turn in the same assignment as cheaters.⁷ In other cultures, individual performance is not as important as the performance of the group. Again, these cultures are collectivist in nature. Consequently, helping a fellow student to understand the assignment and to perform better in the class would be the expectation. Furthermore, this attitude extends to test taking. If a fellow student is struggling on a test and if you were from a collectivist culture, it would be your duty to allow your fellow student to copy your answer. Obviously, this is another example of a substantive cultural difference. From a business perspective, these different views of plagiarism and cheating could have serious implications for the protection of intellectual property.

FIGURE 12-1 Cultural Optical Illusion⁸

Cultural differences also extend to the way we literally see things. A classic image that demonstrates the way our visual perception is affected by our culture and environment is demonstrated in the sketch shown in Figure 12-1. Depending on where you are from, you will focus on and see different things. For example, where does the scene portrayed in the sketch take place? What is the item above the woman's head? Most Westerners say that the scene takes place in a room and the item above the woman's head is a window through which you can see a plant of some sort. However, if you are from East Africa, the scene is believed to take place outside under a tree and the item above the woman's head is actually a box that she is balancing on her head. In East Africa, there are very few homes with corners: Most homes are round. Therefore, the location of the scene must be outside under a tree. Consequently, the item above the women's head cannot be a window. Instead, it must be a box.

In a set of studies comparing East Asians and Americans, Richard Nisbett, of the University of Michigan, and his colleagues has demonstrated that there are cultural differences that not only affect the way individuals see things, but also what they focus on.⁹ For example, in Figure 12-2a, we see an aquarium-like setting. In a recall test, a set of Japanese and American students watched an animation of the aquarium. After watching the aquarium animation, they were asked to recall what they had seen. Both groups were able to recall about the same number of “focal” fish, those that were moving faster and/or were larger. However, the Japanese students were able to recall a lot of the “background” material, such as the bubbles rising in the middle of the tank, the small frog and snail near the bottom of the tank, the plants, and the rocks, whereas the Americans generally could not. In a separate test, where the students were asked whether they had seen the fish before, both the Japanese and American students easily recognized the fish when it was displayed with its original background (see Figure 12-2b). However, the Japanese had a much more difficult time in recognizing the fish when it was portrayed in a different context with a novel background (see Figure 12-2c). According to Nisbett and his colleagues, this result, along with others, provided evidence that Asians tended to bind the focal objects to the environment within which they were first seen, where as Americans simply focuses on the individual objects themselves.

FIGURE 12-2 Asian and American Differences

As we stated previously, with offshore outsourcing, information systems development teams can be geographically dispersed and multicultural in their membership. Given the above issues and when we consider the cultural differences Hall and Hofstede identified (see Chapter 10), cultural issues add a new wrinkle in the management of developing a successful information system.¹⁰ Hall's context dimension partially explains Nisbett's results. From an information systems development perspective, context could influence the ability of a team member to see (or not see) potential creative solutions that are out of the box or affect a team member's ability (or inability) to understand the entire problem under consideration. Furthermore, given this dimension, the level of detail in direction could be varied between cultures. Hofstede's individualism and collectivism dimension partially explains the results regarding plagiarism and cheating described above. Given the importance that intellectual property plays in IT, this potentially could be a real problem when offshoring development to a collectivist culture. Furthermore, Hall's speed of messages and context dimensions could also affect the way this could be addressed. Depending on the culture, too much detail could be insulting, but attempting to put this issue in to a contextual frame that is culturally sensitive is difficult.

When managing programmers in a multicultural setting, Hall's time dimension must also be considered. In monochronic time cultures, deadlines are critical. This is probably why timeboxing has been relatively successful as a method to control projects (see Chapter 2). However, in a polychronic time culture, a deadline is nothing more than a suggestion. Obviously, when managing programmers, understanding how the culture considers time is very important to have both a successful product delivery and a successful development process.

Hofstede's other previously mentioned dimensions are power distance, uncertainty avoidance, and masculinity versus femininity. Managing programmers in a culture with a high power distance value is different than with a culture with a low power distance. For example, in the United States, programmers see themselves as equals to their managers. In fact, in some firms, the president of the firm can be found “coding” solutions along side of a brand new hire. This somewhat explains the growing popularity of agile methods (see Chapter 1). In comparison, in a high power distance culture, the president of the firm would never stoop to performing the same tasks as a new hire. It would be insulting to the president and embarrassing to the new hire.

With regard to uncertainty avoidance, the choice of systems development approach could be affected. In a culture that prefers everything to be neat and ordered, a systems development methodology that is very rule-driven would be beneficial. Also, development team member professional certification and team and firm ISO or CMMI certifications would lend credibility to the team, whereas in a culture that willingly takes on risk, certifications might not increase the perceived standing of the development team.

When managing programmers in a masculine culture, it is critical to provide recognition to the top-performing members of the development team and also to recognize the top-performing teams. On the other hand, when considering a feminine culture, it is more important to ensure that the workplace is a supportive, noncompetitive, and nurturing environment.

Hofstede has identified a fifth dimension, long- versus short-term orientation, which deals with how the culture views the past and the future. In a long-term focused culture, team development and a deep relationship with a client is very important, while in a culture that emphasizes the short term, delivering a high-quality product on time is all that really matters.

For years, project managers in the United States have had to bring together individuals from very different backgrounds. There was always a common spoken and written language, English, and the melting pot idea that guaranteed some level of commonality among the team members.¹¹ However, in today's “flat world,” there is no longer any common culture or common spoken and written language. From an information systems development perspective, the common language today tends to be UML, Java, SQL, C++, Objective-C, and Visual Basic, not English. However, at this time, there is no common culture. Consequently, understanding cultural issues will be extremely important for the near future to successfully manage international and multicultural development teams.

DESIGNING TESTS

In object-oriented systems, the temptation is to minimize testing. After all, through the use of patterns, frameworks, class libraries, and components, much of the system has been tested previously. Therefore, we should not have to test as much. Right? Wrong! Testing is more critical to object-oriented systems than systems developed in the past. Based on encapsulation (and information hiding), polymorphism (and dynamic binding), inheritance, reuse, and the actual object-oriented products, thorough testing is much more difficult and critical. Given the complexity of the development processes used and the global nature of information systems development, testing becomes even more crucial. Thus, object-oriented testing must be done systematically and the results must be documented so that the project team knows what has and has not been tested. Testing object-oriented systems is therefore very complex. Consequently, a complete coverage of the topic is beyond the scope of this book. However, given the importance of testing in developing quality software, in this section we provide a basic overview of object-oriented systems testing.¹²

The purpose of testing is not to demonstrate that the system is free of errors. It is not possible to prove that a system is error free, which is especially true with object-oriented systems. This is similar to theory testing. You cannot prove a theory. If a test fails to find problems with a theory, your confidence in the theory is increased. However, if a test succeeds in finding a problem, then the theory has been falsified. Software testing is similar in that it can only show the existence of errors. The purpose of testing is to uncover as many errors as feasible.¹³

FIGURE 12-3 Error-Discovery Rates for Different Stages of Tests

There are four general stages of tests: unit tests, integration tests, system tests, and acceptance tests. Although each application system is different, most errors are found during integration and system testing (see Figure 12-3).

In each of the following sections, we describe the four stages. However, before doing this, we describe the effect that the object-oriented characteristics have on testing and the necessary planning and management activities that must take place to have a successful testing program.

Testing and Object Orientation

Most testing techniques have been developed to support non-object-oriented development. Therefore, most of the testing approaches have had to be adapted to object-oriented systems. The characteristics of object-oriented systems that affect testing the most are encapsulation (and information hiding), polymorphism (and dynamic binding), inheritance, and the use of patterns, class libraries, frameworks, and components. Also, the sheer volume of products that come out of a typical object-oriented development process has increased the importance of testing in object-oriented systems development.

Encapsulation and Information Hiding Encapsulation and information hiding allow processes and data to be combined to create holistic entities (i.e., objects). They support hiding everything behind a visible interface. Although this allows the system to be modified and maintained in an effective and efficient manner, it makes testing the system problematic. What do you need to test to build confidence in the system's ability to meet the user's need? You need to test the business process that is represented in the use cases. However, the business process is distributed over a set of collaborating classes and contained in the methods of those classes. The only way to know the effect that a business process has on a system is to look at the state changes that take place in the system. But in object-oriented systems, the instances of the classes hide the data behind a class boundary. How is it possible then to see the impact of a business process?

A second issue raised by encapsulation and information hiding is the definition of a “unit” for unit testing. What is the unit to be tested? Is it the package, class, or method? In traditional approaches, the answer would be the process that is contained in a function. However, the process in object-oriented systems is distributed over a set of classes. Therefore, testing individual methods makes no sense. The answer is the class. This dramatically changes the way unit testing is done.

A third issue raised is the impact on integration testing. In this case, objects can be aggregated to form aggregate objects; for instance, a car has many parts, or they can be grouped together to form collaborations. Furthermore, they can be used in class libraries, frameworks, and components. Based on all of these different ways classes can be grouped together, how does one effectively do integration testing?

Polymorphism and Dynamic Binding Polymorphism and dynamic binding dramatically affect both unit and integration testing. Because an individual business process is implemented through a set of methods distributed over a set of objects, as shown before, the unit test makes no sense at the method level. However, with polymorphism and dynamic binding, the same method (a small part of the overall business process) can be implemented in many different objects. Therefore, testing individual implementations of methods makes no sense. Again, the unit that makes sense to test is the class. Except for trivial cases, dynamic binding makes it impossible to know which implementation is going to be executed until the system does it. Therefore, integration testing becomes very challenging.

Inheritance When taking into consideration the issues raised about inheritance (see Chapter 8), it should not be a surprise that inheritance affects the testing of object-oriented systems. Through the use of inheritance, bugs can be propagated instantaneously from a superclass to all its direct and indirect subclasses. However, the tests that are applicable to a superclass are also applicable to all its subclasses. As usual, inheritance is a double-edged sword. Finally, even though we have stated this many times before, inheritance should support only a generalization and specialization type of semantics. Remember, when using inheritance, the principle of substitutability is critical (see Chapter 5). All these issues affect unit and integration testing.

Reuse On the surface, reuse should decrease the amount of testing required. However, each time a class is used in a different context, the class must be tested again. Therefore, any time a class library, framework, or component is used, unit testing and integration testing are important. In the case of a component, the unit to test is the component itself. Remember that a component has a well-defined API (application program interface) that hides the details of its implementation.

Object-Oriented Development Process and Products In virtually all textbooks, including this one, testing is covered near the end of system development. This seems to imply that testing is something that takes place only after the programming has ended. However, every product¹⁴ that comes out of the object-oriented development process must be tested. For example, it is a lot easier to ensure that the requirements are captured and modeled correctly through testing the use cases, and it is a lot cheaper to catch this type of error back in analysis than it is in implementation. Obviously, this is also true for testing collaborations. By the time we have implemented a collaboration as a set of layers and partitions, we could have expended a great deal of time—and time is money—on implementing the wrong thing. So testing collaborations by role-playing the CRC cards in analysis actually saves the team lots of time and money.

Testing is something that must take place throughout system development, not simply at the end. However, the type of testing that can take place on nonexecutable representations, such as use cases and CRC cards, is different from those on code written in an object-oriented programming language. The primary approach to testing nonexecutable representations is some form of an inspection or walkthrough of the representation.¹⁵ Role-playing the CRC cards based on use cases is an example of one type of walkthrough.

Test Planning

Testing starts with the development of a test plan, which defines a series of tests that will be conducted. Because testing takes place throughout the development of an object-oriented system, a test plan should be developed at the very beginning of system development and continuously updated as the system evolves. For example, the representation of a class evolves from a simplistic CRC card to a set of classes that are implemented in a programming language. In Figure 12-4 we see a CRC card representation of an Order class that contains invariants. Each of these invariants must be tested and enforced for the Order class to be considered to be of sufficient quality. One simple invariant test would be to attempt to assign a value to the Cust ID attribute that was not associated with the Customer object that is contained in the Customer attribute. Another invariant test would be to try and assign more than one date to the Date attribute. Finally, a trickier invariant test would be to try to assign an integer value to the Shipping attribute. This one is more difficult because most programming languages allow an integer to be “cast” to a double. If the value contained in the Shipping attribute really is supposed to be a double, then casting the integer value to a double would be an error. These tests should be done using a walkthrough approach when the class is specified, as we did in Chapters 4, 5, 6, and 7, and a more rigorous approach once the class has been fully implemented. This is an example of unit testing a class, which is described in the next section. To ensure the quality of a class, it should be tested each time its representation is changed.

The test plan should address all products that are created during the development of the system. For example, tests should be created that can be used to test completeness of a CRC card. Each individual test has a specific objective and describes a set of very specific test cases to examine. In the case of invariant-based tests, a description of the invariant is given, and the original values of the attribute, the event that will cause the attribute value to change, the actual results observed, the expected results, and whether it passed or failed are shown. Test specifications are created for each type of constraint that must be met by the class. Also, similar types of specifications are done for integration, system, and acceptance tests.

Not all classes are likely to be finished at the same time, so the programmer usually writes stubs for the unfinished classes to enable the classes around them to be tested. A stub is a placeholder for a class that usually displays a simple test message on the screen or returns some hardcoded value¹⁶ when it is selected. For example, consider an application system that provides creating, changing, deleting, finding, and printing functions for some object such as CDs, patients, or employees. Depending on the final design, these different functions could end up in different objects on different layers. Therefore, to test the functionality associated with the classes on the problem-domain layer, a stub would be written for each of the classes on the other layers that interact with the problem-domain classes. These stubs would be the minimal interface necessary to be able to test the problem-domain classes. For example, they would have methods that could receive the messages being sent by the problem-domain layer objects and methods that could send messages to the problem-domain layer objects. Typically, the methods would display a message on the screen notifying the tester that the method was successfully reached (e.g., Delete item from Database method reached). In this way, the problem-domain classes could pass class testing before the classes on the other layers were completed.

FIGURE 12-4 Order CRC Card (see Figure 8-19)

Unit Tests

Unit tests focus on a single unit—the class. There are two approaches to unit testing: black-box testing and white-box testing (see Figure 12-5). Black-box testing is the most commonly used because each class represents an encapsulated object. Black-box testing is driven by the CRC cards, behavior state machines, and contracts associated with a class, not by the programmers’ interpretation. In this case, the test plan is developed directly from the specification of the class: each item in the specification becomes a test, and several test cases are developed for it. White-box testing is based on the method specifications associated with each class. However, white-box testing has had limited impact in object-oriented development. This is due to the rather small size of the individual methods in a class. Most approaches to testing classes use black-box testing to ensure their correctness.

Class tests should be based on the invariants on the CRC cards, the behavioral state machines associated with each class, and the pre- and post-conditions contained on each method's contract. Assuming all the constraints have been captured on the CRC cards and contracts, individual test cases can be developed fairly easily. For example, suppose the CRC card for an order class gave an invariant that the order quantity must be between 10 and 100 cases. The tester would develop a series of test cases to ensure that the quantity is validated before the system accepts it. It is impossible to test every possible combination of input and situation; there are simply too many possible combinations. In this example, the test requires a minimum of three test cases: one with a valid value (e.g., 15), one with a low invalid value (e.g., 7), and one with a high invalid value (e.g., 110). Most tests would also include a test case with a nonnumeric value to ensure the data types were checked (e.g., ABCD). A really good test would include a test case with nonsensical but potentially valid data (e.g. 21.4).

Using a behavioral state machine is a useful way to identify tests for a class. Any class that has a behavioral state machine associated with it has a potentially complex life cycle. It is possible to create a series of tests to guarantee that each state can be reached. For example, Figure 12-6 portrays the behavioral state machine for the Order class just discussed. In this case, there are many transitions between the different states of an instance of the Order class. Tests should be created to guarantee that the only transitions allowed from an instance of the Order class are the ones specifically defined. In this case, it should be impossible for an Order object to go from the In process state to the Placed state without traversing the Ordered and Processing states via the Customer submits order, Order sent for credit authorization, and Authorization = Approved transitions. This state-based testing can be done throughout the development of the class via walkthroughs and role-playing early in the evolution of the class and more rigorous testing once it has been implemented in a programming language.

FIGURE 12-5 Types of Tests

FIGURE 12-6 Order Behavioral State Machine (see Figure 6-17)

FIGURE 12-7 addOrder Contract (see Figure 8-25)

Tests also can be developed for each contract associated with the class. In the case of a contract, a set of tests for each pre- and post-condition is required. For example, the contract of the addOrder method of the Customer class shown in Figure 12-7 has both a pre- and post-condition that essentially requires the new order to have not existed with the instance of the Customer class before the method executes and that it is associated with the Customer object after the method executes. Tests must be created to enforce these constraints. If the class is a subclass of another class, then all the tests associated with the superclass must be executed again. The interactions among the constraints, invariants, and the pre- and post-conditions in the subclass and the superclass(es) must be also addressed.

Finally, owing to good object-oriented design, to fully test a class, special testing methods might have to be added to the class being tested. For example, how can invariants be tested? The only way to really test them is to have methods that are visible to the outside of the class that can be used to manipulate the values of the class's attributes. However, adding these types of methods to a class does two things. First, they add to the testing requirements because they themselves have to be tested. Second, if they are not removed from the deployed version of the system, the system will be less efficient, and the advantage of information hiding effectively is lost. As is readily apparent, testing classes is complex. Therefore, great care must be taken when designing tests for classes.

Integration Tests

Integration tests assess whether a set of classes that must work together do so without error. They ensure that the interfaces and linkages between different parts of the system work properly. At this point, the classes have passed their individual unit tests, so the focus now is on the flow of control among the classes and on the data exchanged among them. Integration testing follows the same general procedures as unit testing: the tester develops a test plan that has a series of tests, which, in turn, have a test. Integration testing is often done by a set of programmers and/or systems analysts.

From an object-oriented systems perspective, integration testing can be difficult. A single class can be in many different aggregations, because of the way objects can be combined to form new objects, class libraries, frameworks, components, and packages. Where is the best place to start the integration? Typically, the answer is to begin with the set of classes, a collaboration, that are used to support the highest-priority use case (see Chapter 4). Also, dynamic binding makes it crucial to design the integration tests carefully to ensure the combinations of methods are tested.

There are four approaches to integration testing: user interface testing,¹⁷ use-case testing, interaction testing, and system interface testing (see Figure 12-5). Most projects use all four approaches. However, like unit testing, integration testing must be carefully planned. In the case of use-case testing, only the aspects of the class and class invariants related to the specific use case are included in these use-case context-dependent class tests. In fact, typically use-case testing is performed one scenario at a time. In many ways, use-case testing can be viewed as a more rigorous role-playing exercise (see Chapter 5). Like unit testing, integration testing should be performed throughout the evolution of the system. In the early stages of the system's development, you should be working with the CRC cards and role-playing them. Later on, you will have the contracts and method specifications completed. Gradually, you will have implemented the problem domain classes, the user interface classes, and the data management layer classes in a programming language. As in unit testing, each time a new representation (diagram, text, program) is created, a new integration test needs to be performed. Therefore, as the system evolves to more completely support the use case, we can more rigorously test whether the use case is fully supported or not.

One of the major problems with integration testing and object-oriented systems is the difficulty caused by the interaction of inheritance and dynamic binding. This specific problem has become known as the yo-yo problem. The yo-yo problem occurs when the analyst or designer must bounce up and down through the inheritance graph to understand the control flow through the methods being executed. In most cases, this is caused by a rather deep inheritance graph; that is, the subclass has many superclasses above it in the inheritance graph. The yo-yo problem becomes even more of a nightmare in testing object-oriented systems when inheritance conflicts exist and when multiple inheritance is used (See Chapter 8). About the only realistic approach to testing through the yo-yo problem is through an interactive debugger that is typically part of a systems development environment, such as Eclipse, Netbeans, or Visual Studio.

System Tests

System tests are usually conducted by the systems analysts to ensure that all classes work together without error. System testing is similar to integration testing but is much broader in scope. Whereas integration testing focuses on whether the classes work together without error, system tests examine how well the system meets business requirements and its usability, security, and performance under heavy load (see Figure 12-5). It also tests the system's documentation.

Acceptance Tests

Acceptance testing is done primarily by the users with support from the project team. The goal is to confirm that the system is complete, meets the business needs that prompted the system to be developed, and is acceptable to the users. Acceptance testing is done in two stages: alpha testing, in which users test the system using made-up data, and beta testing, in which users begin to use the system with real data but are carefully monitored for errors (see Figure 12-5).

DEVELOPING DOCUMENTATION

Like testing, developing documentation of the system must be done throughout system development. There are two fundamentally different types of documentation: system documentation and user documentation. System documentation is intended to help programmers and systems analysts understand the application software and enable them to build it or maintain it after the system is installed. System documentation is largely a by-product of the systems analysis and design process and is created as the project unfolds. Each step and phase produces documents that are essential in understanding how the system is or is to be built, and these documents are stored in the project binder(s). In many object-oriented development environments, it is possible to somewhat automate the creation of detailed documentation for classes and methods. For example, in Java, if the programmers use javadoc-style comments, it is possible to create HTML pages that document a class and its methods automatically by using the javadoc utility.¹⁸ Because most programmers look on documentation with much distaste, anything that can make documentation easier to create is useful.

User documentation (such as user's manuals, training manuals, and online help systems) is designed to help the user operate the system. Although most project teams expect users to have received training and to have read the user's manuals before operating the system, unfortunately, this is not always the case. It is more common today—especially in the case of commercial software packages for microcomputers—for users to begin using the software without training or reading the user's manuals. In this section, we focus on user documentation.¹⁹

User documentation is often left until the end of the project, which is a dangerous strategy. Developing good documentation takes longer than many people expect because it requires much more than simply writing a few pages. Producing documentation requires designing the documents (whether on paper or online), writing the text, editing the documents, and testing them. For good-quality documentation, this process usually takes about three hours per page (single-spaced) for paper-based documentation or two hours per screen for online documentation. Thus a “simple” documentation, such as a ten-page user's manual and a set of twenty help screens, takes seventy hours. Of course, lower-quality documentation can be produced faster.

The time required to develop and test user documentation should be built into the project plan. Most organizations plan for documentation development to start once the interface design and program specifications are complete. The initial draft of documentation is usually scheduled for completion immediately after the unit tests are complete. This reduces (but doesn't eliminate) the chance that the documentation will need to be changed owing to software changes and still leaves enough time for the documentation to be tested and revised before the acceptance tests are started.

Although paper-based manuals are still important, online documentation is becoming more important. Paper-based documentation is simpler to use because it is more familiar to users, especially novices who have less computer experience; online documentation requires the users to learn one more set of commands. Paper-based documentation is also easier to flip through and gain a general understanding of its organization and topics and can be used far away from the computer itself.

There are four key strengths of online documentation that all but guarantee it will be the dominant form for the 21st century. Searching for information is often simpler (provided the help search index is well designed) because the user can type in a variety of keywords to view information almost instantaneously, rather than having to search through the index or table of contents in a paper document. The same information can be presented several times in many different formats, so that the user can find and read the information in the most informative way (such redundancy is possible in paper documentation, but the cost and intimidating size of the resulting manual make it impractical). Online documentation provides many new ways for the user to interact with the documentation that is not possible in static paper documentation. For example, it is possible to use links, or “tool tips” (i.e., pop-up text; see Chapter 10) to explain unfamiliar terms, and one can write “show-me” routines that demonstrate on the screen exactly what buttons to click and text to type. Finally, online documentation is significantly less expensive to distribute than paper documentation.

Types of Documentation

There are three fundamentally different types of user documentation: reference documents, procedures manuals, and tutorials. Reference documents (also called the help system) are designed to be used when the user needs to learn how to perform a specific function (e.g., updating a field, adding a new record). Often people read reference information when they have tried and failed to perform the function; writing reference documents requires special care because the user is often impatient or frustrated when he or she begins to read them.

Procedures manuals describe how to perform business tasks (e.g., printing a monthly report, taking a customer order). Each item in the procedures manual typically guides the user through a task that requires several functions or steps in the system. Therefore, each entry is typically much longer than an entry in a reference document.

Tutorials—obviously—teach people how to use major components of a system (e.g., an introduction to the basic operations of the system). Each entry in the tutorial is typically longer still than the entries in procedures manuals, and the entries are usually designed to be read in sequence (whereas entries in reference documents and procedures manuals are designed to be read individually).

Regardless of the type of user documentation, the overall process for developing it is similar to the process of developing interfaces (see Chapter 10). The developer first designs the general structure for the documentation and then develops the individual components within it.

Designing Documentation Structure

In this section, we focus on the development of online documentation, because we believe it will become the most common form of user documentation. The general structure used in most online documentation, whether reference documents, procedures manuals, or tutorials, is to develop a set of documentation navigation controls that lead the user to documentation topics. The documentation topics are the material that user wants to read, whereas the navigation controls are the way the user locates and accesses a specific topic.

Designing the structure of the documentation begins by identifying the different types of topics and navigation controls that need to be included. Figure 12-8 shows a commonly used structure for online reference documents (i.e., the help system). The documentation topics generally come from three sources. The first and most obvious source of topics is the set of commands and menus in the user interface. This set of topics is very useful if the user wants to understand how a particular command or menu is used.

However, the users often don't know what commands to look for or where they are in the system's menu structure. Instead, users have tasks they want to perform, and rather than thinking in terms of commands, they think in terms of their tasks. Therefore, the second and often more useful set of topics focuses on how to perform certain tasks, usually those in the use scenarios, WND, and the real use cases from the user interface design (see Chapter 10). These topics walk the user through the set of steps (often involving several keystrokes or mouse clicks) needed to perform some task.

The third topic is definitions of important terms. These terms are usually the use cases and classes in the system, but sometimes they also include commands.

There are five general types of navigation controls for topics, but not all systems use all five types (see Figure 12-8). The first is the table of contents that organizes the information in a logical form, as though the users were to read the reference documentation from start to finish. The index provides access into the topics based on important keywords, in the same way that the index at the back of a book helps us find topics. Text search provides the ability to search through the topics either for any text the user types or for words that match a developer-specified set of words that is much larger than the set of words in the index. Unlike the index, text search typically provides no organization to the words (other than alphabetical). Some systems provide the ability to use an intelligent agent to help in the search. The fifth and final navigation controls to topics are the hyperlinks between topics that enable the user to click and move among topics.

Procedures manuals and tutorials are similar but often simpler in structure. Topics for procedures manuals usually come from the use scenarios, WNDs, and the real use cases developed during interface design and from other basic tasks the users must perform. Topics for tutorials are usually organized around major sections of the system and the level of experience of the user. Most tutorials start with the basic, most commonly used commands and then move into more complex and less commonly used commands.

FIGURE 12-8 Organizing Online Reference Documents

Writing Documentation Topics

The general format for topics is fairly similar across application systems and operating systems (see Figure 12-9). Topics typically start with very clear titles, followed by some introductory text that defines the topic and then by detailed, step-by-step instructions on how to perform what is being described. Many topics include screen images to help the user find items on the screen; some also have tutorials and videos available online that demonstrate the functions of interest to the user. Most also include navigation controls to enable the movement among topics, usually at the top of the window, plus links to other topics. Some also include links to related topics that include options or other commands and tasks the user might want to perform in concert with the topic being read.

FIGURE 12-9 A Help Topic in Microsoft Word 2011

Writing the topic content can be challenging. It requires a good understanding of the user (or more accurately the range of users) and a knowledge of what skills the users currently have and can be expected to import from other systems and tools they are using or have used (including the system that the new system is replacing). Topics should always be written from the viewpoint of the user and describe what the user wants to accomplish, not what the system can do. Figure 12-10 provides some general guidelines to improve the quality of documentation text.²⁰

Identifying Navigation Terms

As we write the documentation topics, we also begin to identify the terms that will be used to help users find topics. The table of contents is usually the most straightforward, because it is developed from the logical structure of the documentation topics, whether reference topics, procedure topics, or tutorial topics. The items for the index and search engine require more care because they are developed from the major parts of the system and the users’ business functions. Every time we write a topic, we must also list the terms that will be used to find the topic. Terms for the index and search engine can come from four distinct sources.

FIGURE 12-10 Guidelines for Crafting Documentation Topics

The first source for index terms is the set of the commands in the user interface, such as open file, modify customer, and print open orders. All commands contain two parts (action and object). It is important to develop the index for both parts because users could search for information using either part. A user looking for more information about saving files, for example, might search by using the term save or the term files.

The second source is the set of major concepts in the system, which are often use cases and classes. In the case of the Appointment system, for example, this might include appointment, symptoms, or patient.

A third source is the set of business tasks the user performs, such as ordering replacement units or making an appointment. Often these are contained in the command set, but sometimes they require several commands and use terms that do not always appear in the system. Good sources for these terms are the use scenarios and real use cases developed during interface design (see Chapter 10).

A fourth, often controversial, source is the set of synonyms for the three sets of preceding items. Users sometimes don't think in terms of the nicely defined terms used by the system. They might try to find information on how to stop or quit rather than exit, or erase rather than delete. Including synonyms in the index increases the complexity and size of the documentation system but can greatly improve the usefulness of the system to the users.

SUMMARY

Managing Programming

Programming is done by programmers, so systems analysts have few responsibilities during this stage. The project manager, however, is usually very busy. The first task is to assign the programmers to complete the project, ideally the fewest possible because coordination problems increase as the size of the programming team increases. Coordination can be improved by having regular meetings, ensuring that standards are followed, implementing change control, and using CASE tools effectively. One of the key functions of the project manager is to manage the schedule and adjust it for delays. Two common causes of delays are scope creep and minor slippages that go unnoticed. Given today's global development of information systems, different cultural issues need to be taken into consideration.

Designing Tests

Tests must be carefully planned because the cost of fixing one major bug after the system is installed can easily exceed the annual salary of a programmer. A test plan contains several tests that examine different aspects of the system. A test, in turn, specifies several test cases that will be examined by the testers. A unit test examines a class within the system; test cases come from the class specifications or the class code itself. An integration test examines how well several classes work together; test cases come from the interface design, use cases, and the use-case, sequence, and collaboration diagrams. A system test examines the system as a whole and is broader than the unit and integration tests; test cases come from the system design, the infrastructure design, the unit, and integration tests. Acceptance testing is done by the users to determine whether the system is acceptable to them; it draws on the system test plans (alpha testing) and the real work the users perform (beta testing).

Developing Documentation

Documentation, both user documentation and system documentation, is moving away from paper-based documents to online documentation. There are three types of user documentation: Reference documents are designed to be used when the user needs to learn how to perform a specific function (e.g., an online help system), procedures manuals describe how to perform business tasks, and tutorials teach people how to use the system. Documentation navigation controls (e.g., a table of contents, index, find, intelligent agents, or links between pages) enable users to find documentation topics (e.g., how to perform a function, how to use an interface command, an explanation of a term).

KEY TERMS

1. Acceptance test, 535
2. Alpha test, 535
3. Beta test, 535
4. Black-box testing, 530
5. Change control, 519
6. Collectivism, 523
7. Construction, 516
8. Context, 523
9. Documentation navigation control, 537
10. Documentation topic, 537
11. Femininity, 524
12. Hardcoded, 530
13. Individualism, 523
14. Integration test, 534
15. Interaction testing, 534
16. Long-term orientation, 524
17. Masculinity, 524
18. Monochronic time, 524
19. Polychronic time, 524
20. Power distance, 524
21. Procedures manual, 536
22. Program log, 519
23. Reference document, 536
24. Requirements testing, 531
25. Security testing, 531
26. Short-term orientation, 524
27. Speed of messages, 524
28. Stub, 428
29. System documentation, 535
30. System interface testing, 534
31. System test, 534
32. Test case, 528
33. Test plan, 528
34. Test specification, 528
35. Time, 524
36. Timeboxing, 524
37. Traceability, 516
38. Tutorial, 536
39. Uncertainty avoidance, 524
40. Unit test, 530
41. Usability testing, 531
42. Use-case testing, 534
43. User documentation, 535
44. User interface testing, 534
45. White-box testing, 530
46. Yo-yo problem, 534

QUESTIONS

1. Why is testing important?
2. How can different national or organizational cultures affect the management of an information systems development project?
3. What is the primary role of systems analysts during the programming stage?
4. In The Mythical Man-Month, Frederick Brooks argues that adding more programmers to a late project makes it later. Why?
5. When offshoring development, how could differences in Hall's context dimension of culture affect the contribution of a team member to the successful development of an information system? What about Hall's time or speed of messages dimensions?
6. What are Hofstede's five dimensions of cultural differences? How could differences in them influence the effectiveness of an information systems development team?
7. What are the common language or languages used today in information systems development?
8. What is the purpose of testing?
9. Describe how object orientation affects testing.
10. Compare and contrast the terms test, test plan, and test case.
11. What is a stub and why is it used in testing?
12. What is the primary goal of unit testing?
13. How are the test cases developed for unit tests?
14. Compare and contrast black-box testing and white-box testing.
15. What are the different types of class tests?
16. What is the primary goal of integration testing?
17. How are the test cases developed for integration tests?
18. Describe the yo-yo problem. Why does it make integration testing difficult?
19. What is the primary goal of system testing?
20. How are the test cases developed for system tests?
21. What is the primary goal of acceptance testing?
22. How are the test cases developed for acceptance tests?
23. Compare and contrast alpha testing and beta testing.
24. Compare and contrast user documentation and system documentation.
25. Why is online documentation becoming more important?
26. What are the primary disadvantages of online documentation?
27. Compare and contrast reference documents, procedures manuals, and tutorials.
28. What are five types of documentation navigation controls?
29. What are the commonly used sources of documentation topics? Which is the most important? Why?
30. What are the commonly used sources of documentation navigation controls? Which is the most important? Why?

EXERCISES

1. Different views of plagiarism and collaborative learning were described as examples of differences among different cultures today. Using the Web, identify other differences that could affect the success of an information systems development team.
2. Besides Hall and Hofstede, both David Victor and Fons Trompenaars have identified a set of cultural dimensions that could be useful in information systems development. Using the Web, identify their dimensions.
3. If the registration system at your university does not have a good online help system, develop one for one screen of the user interface.
4. Examine and prepare a report on the online help system for the calculator program in Windows (or a similar one on the Mac or Unix). (You will probably be surprised at the amount of help for such a simple program.)
5. Compare and contrast the online help at two different Web sites that enable you to perform some function (e.g., make travel reservations, order books).
6. Create an invariant test specification for the class you chose for the A Real Estate Inc. problem in exercise A in Chapter 8.
7. Create a use-case test plan, including the specific class plans and invariant tests, for a use case from the A Real Estate Inc. exercises in the previous chapters.
8. Create an invariant test specification for the class you chose for the A Video Store problem in exercise B in Chapter 8.
9. Create a use-case test plan, including the specific class plans and invariant tests, for a use case from the A Video Store exercises in the previous chapters.
10. Create an invariant test specification for the class you chose for the gym problem in exercise C in Chapter 8.
11. Create a use-case test plan, including the specific class plans and invariant tests for a use case from the health club exercises in previous chapters.
12. Create an invariant test specification for the class you chose for Picnics R Us in exercise D in Chapter 8.
13. Create a use-case test plan, including the specific class plans and invariant tests, for a use case from the Picnics R Us exercises in the previous chapters.
14. Create an invariant test specification for the class you chose for the Of-the-Month Club (OTMC) in exercise E in Chapter 8.
15. Create a use-case test plan, including the specific class plans and invariant tests, for a use case from the Of-the-Month Club (OTMC) exercises in the previous chapters.

MINICASES

1. Pete is a project manager on a new systems development project. This project is Pete's first experience as a project manager, and he has led his team successfully to the programming phase of the project. The project has not always gone smoothly, and Pete has made a few mistakes, but he is generally pleased with the progress of his team and the quality of the system being developed. Now that programming has begun, Pete has been hoping for a little break in the hectic pace of his workday.

   Prior to beginning programming, Pete recognized that the time estimates made earlier in the project were too optimistic. However, he was firmly committed to meeting the project deadline because of his desire for his first project as project manager to be a success. In anticipation of this time pressure problem, Pete arranged with the Human Resources department to bring in two new college graduates and two college interns to beef up the programming staff. Pete would have liked to find some staff with more experience, but the budget was too tight, and he was committed to keeping the project budget under control.

   Pete made his programming assignments, and work on the programs began about two weeks ago. Now, Pete has started to hear some rumbles from the programming team leaders that might signal trouble. It seems that the programmers have reported several instances where they wrote programs, only to be unable to find them when they went to test them. Also, several programmers have opened programs that they had written, only to find that someone had changed portions of their programs without their knowledge.

   1. Is the programming phase of a project a time for the project manager to relax? Why or why not?
   2. What problems can you identify in this situation?
   3. What advice do you have for the project manager? How likely does it seem that Pete will achieve his desired goals of being on time and within budget if nothing is done?
2. The systems analysts are developing the test plan for the user interface for the Holiday Travel Vehicles system. As the salespeople are entering a sales invoice into the system, they will be able to enter an option code into a text box or to select an option code from a drop-down list. A combo box was used to implement this, because it was felt that the salespeople would quickly become familiar with the most common option codes and would prefer entering them directly to speed up the entry process.

   It is now time to develop the test for validating the option code field during data entry. If the customer did not request any dealer-installed options for the vehicle, the salesperson should enter “none”; the field should not be blank. The valid option codes are four-character alphabetic codes and should be matched against a list of valid codes.

   Prepare a test plan for the test of the option code field during data entry.