Packaging the Product

Our customers had been working with PSP Tools for a while. Russell knew the product almost as well as the rest of the development team. What was the best way to deliver the product to our users? What exactly did we plan to distribute?

One possibility was to expend minimal effort and just package the Java Archive (JAR) file and other libraries, and then email it to the users. We could even post it to a Web site and let anyone download it. But would that be good enough? We believed that without support and training materials, new users would be stuck. We wanted to attract users who are not members of Russell's development staff.

We decided that our distribution package needed to contain the following items:

• The software product itself

• An introduction for new users

• Installation instructions

• Release notes to describe final changes for existing users of the software

Our Transition phase plan was simple. We gave everyone on the team a set of deliverables, let them think about how much time and effort they would need to produce the deliverables, added some additional time for fixing any defects that might crop up, and established a release date. If a feature isn't ready for release in an earlier iteration, you simply move it to a future iteration and perform the required scope management. During the Transition phase, the end date becomes more critical; you must plan and monitor the schedule and work products more carefully than in other phases. Your customers are waiting for delivery of the product and you've promised that they can have it. If you miss this date, most of the goodwill that you have gained from your customers will be lost.

Iterative development is great. It helps you focus on producing working software. As you reach the end of your project, however, you need to reserve time to work on the final packaging. You may have been extremely agile and responsive to changes during the project. We feel that at the end of the Transition phase, you shouldn't implement new requirements or produce new code. Instead, you should focus on packaging and deployment of your software. Similarly, your customers need to plan to accept and use the software, including any transitions from old systems or previous releases of the software. Planning, rather than responding to change, is critical for this part of the process.

If you restrict the Transition phase to work on the final packaging, support materials, and fixing only critical defects, you will find that you can meet the schedule you establish for your Transition phase iteration or iterations. When you add tasks that aren't in the established short list, you risk a delay in delivering the finished product to your customers.

User Documentation

We were very lucky to have Liz on our team. She's got a wealth of experience in producing documentation for many different types of users. Her ability to relate to the customer was valuable to the team when we worked on use cases and again when we designed the user interface. As a user advocate, she helped us think about what the customer might, or might not, understand about the product, or discover while using the product.

There are many books that say a lot about user documentation ”how to write it, what it must contain, and different ways to present it. ^[7] We want to emphasize that unless you have designed the perfect program, or unless your program requires no user interaction, you need some type of user documentation. And your documentation should be useful to your end users.

^[7] To explore this topic more fully than we can in this book, go to http://www.amazon.com and search under Books for "software technical writing."

The practice of writing user documentation has gone through several trends over the last few decades. Several years ago, the trend was to faithfully document every aspect of the user interface, leading to the following all-too-ubiquitous classic piece of "help": Click File > New to create a new file.

This type of user assistance isn't very helpful; it doesn't answer questions that real users might ask, such as:

• Under what circumstances would you want to create a new file?

• What are the alternatives to creating a new file (perhaps working in a temporary space)?

• Are there any restrictions (for example, on the length of the file name or the type of file)?

• What if something goes wrong while I'm creating a file?

• Are there related activities that I should know about (deleting a file, renaming a file)?

After just a few encounters with this type of documentation, most users learn to distrust , and eventually avoid, reading the very documentation that is supposed to be helping them effectively use the software.

Fortunately, a relatively recent trend in technical documentation has helped technical writers produce user assistance that is actually helpful. In the industry, this trend is called " task-oriented writing" or "user-centered information development."

The PSP Tools User's Guide follows this trend in that it is structured around the tasks that a user might perform to get value from using the software. Does this sound familiar? It should ”it's one of the ways to define a use case.

We have already mentioned several reasons to work with use cases on your project, and using them as a foundation for writing effective user documentation is another one. If you structure the documentation by starting with use cases, you provide information that helps the users do their jobs, rather than documentation that simply describes the features of the product.

This approach fits neatly into Liz's philosophy about technical writing. She believes that most people don't use software for its own sake (because it's fun, for example); they use software so they can be more effective at doing their jobs. After all, most of us want to get our work done with minimal fuss. We want our tools to work, and when we need help, we want to find the information quickly and get back to the task. Liz believes that her job is to "help people go home at night." By organizing and presenting documentation in terms of what the user is trying to accomplish, she feels that she can be more successful at her craft.

Originally, we planned to deliver documentation as online help. Partway through the project, we decided to write a User's Guide instead, and not provide online help, at least not for version 1. ^[8]

^[8] The full User's Guide is available on the book's Web site.

Figure 10.1 shows the guide's Table of Contents. It is short but you can immediately see how to get value from the product. Notice that the headings don't exactly map to the use cases, but they do follow the general scenarios in the use cases. If you aren't already producing user documentation based on use cases, try it and see how your users like it.

Figure 10.1. PSP Tools User's Guide table of contents

You want to involve technical writers in the project as early as you can hire them. Documentation work continues throughout the project. During the Transition phase, documentation work focuses on attending to the final publishing details to prepare the material for your customers.

Writers typically work with testers, engineers , product managers, and even customers to understand the goals of the product and how to use it. Writers can be excellent user advocates, and they can help develop use cases and assist with the design of user interfaces. As the writers learn the software (in preparation for writing about it), they can serve as an early warning system when the software doesn't work as expected or when it seems to veer away from the use cases. Writers can contribute a great deal to the project. We encourage you to get writers involved early in your projects.