Section 11.7. Documenting, Prototyping, and Stakeholder Buy-In

11.7. Documenting, Prototyping, and Stakeholder Buy-In

Once a project is started, the design must be documented. A prototype may be built to validate and refine the design. Finally, everyone with a stake in the success of the design has to be brought up to speed and needs to agree on what is to be built.

11.7.1. Documenting

After such a conversation, it's smart to try to get your thoughts down on paper as soon as possible. Some of what gets said will fade with time, so work quickly to capture what you can of the requirements that were spoken. Even if you have to leave lots of blanks, keep moving and get as much of the major requirements written down as you can, even if they don't sound very formal or polished. Then go back, revise and edit your statements, filling in the blanks where you can. Sometimes you will need to ask others to get the answers to fill in the blanks. Other times you can use your own judgment and initiative to provide an answer. Out of this process with its subsequent rewrites will come the requirements document.

Some organizations are very formal in their understanding of requirements. They will have company-standard formats which you must follow. But there is no magic format that will make for good requirements. It really all comes down to content.

Here's an informal list of the requirements for the budget application, based on the conversation between Bob and Ellen.

Features:

• Starts with a single lump sum of dollars.

  • How does this first sum get entered?

• Each dollar amount is associated with an "account."

• Any account may be divided into two or more subaccounts.

• The dollar amount associated with a subaccount is specified either in absolute dollars or as a percentage.

  • What if they don't add up?

  • Can the user mix $ and %?

  • Can the user leave the last subaccount's amount blank for "remaining dollars"?

• Tracking of the dollarsnot enough info, so not in first prototype.

• Multiple users will have access to the data.

• Concurrent use is allowed and supported.

• Short development time, limited resources.

• Has a graphical user interface; earliest versions may be command-line and terminal interaction.

Not all requirements will be easily forthcoming; not all can be traced back to an exact quote from the previous discussion. Other requirements will need to be inferred from the discussion or from department "culture," or come from your own judgment:

• Platform: "any" PC in Ellen's departmentbut her developers are all using Linux platforms.

• Future platforms: "any" PC in the company means any Windows, Linux, or Mac OS X.

• Reliability: once entered, data is never lost.

• Maintainability: the application must be easy to maintain.

• Interoperability: there's no requirement to interoperate with any other software but here's an idea for a future version: export/import into CSV format for spreadsheets, and/or XML format for future expansion).

• Response time: "reasonable" interactive speed; subsecond response when entering new accounts and values, so that the user can type quickly and continuously; waiting, if it occurs, should only be at button presses, not between data entries.

11.7.2. Stakeholder Buy-In

Stakeholder buy-in can be another important part of a software project. As we discussed in Section 11.5, stakeholders are any of those people who are touched in some way, direct or indirect, by this software project.

For this simple budgeting program, there will be few stakeholdersit will largely be Ellen and her direct reports. The system will not likely be a large drain on computing resources, so system admins don't need to be brought in at this point. If and when the project expands to include other users across the network and across the enterprise, then the system administrators should definitely be included. There will be few reports from this first cut of the project, and what few there are will only be read by Ellen and her direct reports, so again, there are few others that need to be consulted as stakeholders.

The idea at this stage is to listen to other points of viewthose of your stakeholdersto get a different perspective before charging headlong down one avenue of development.

It's not that you will be able to satisfy all points of viewit can be a worthy goal, but it is often unattainable. Rather, you need to hear from all those involved since your software will affect all those people, and understanding something about how it will fit into their roles and daily tasks will help you make better tradeoffs and design better software. It will likely uncover previously unseen requirements. It also has the political benefit of those people knowing that you cared enough to listen to them before sending them a finished solution. It increases the likelihood that your software will be seen as a help, not hinderance.^[4]

^[4] As engineering types it is difficult for us to understand and appreciate the importance of this, but in many ways these personal, political, and psychological factors are much more important to the success of a project than are technical choices. It has taken us years to appreciate that Dale Carnegie is as important to the software designer as Yourden or Booch. Your users need to be your friends if you want to succeed.

11.7.3. Prototyping

Prototyping can be an effective way to carry on the discussion of both requirements and user interface design. Given only a hypothetical or abstract description of some software, it can be very difficult for people to imagine what the implications of its use will be. A simple prototype can immediately bring the discussion down to the concrete; people can point at things and say "I like this" and "I don't like that" and "How would I do so-and-so" and then see whether or not it would work. Sometimes, ideas that sound great on paper turn out to be pretty poor ideas when realized. Prototypes can help you discover that quickly and easily.

One very useful but inexpensive prototyping mechanism can be HTMLthat is, creating Web pages. Simple static HTML can be fast and cheap to build, but can begin to approximate what the user interaction will look likeespecially for, but not only for, Web-based solutions. It may not be an exact replica of the final product, but for a first step it can really get the discussion moving.

If the UI is too complex for a Web page mock-up, you can still use HTML for prototyping by getting images (screenshots) of what you want your final solution to look like and then making these images clickable on Web pages, to simulate some simple user interaction with hyperlinked image sequences.

The idea is to get something "tangible" in front of people as soon as possible, to further the discussion in a way that written descriptions never can. ("A picture is worth a thousand words.")

Once you've built a prototype, shop it around. Hold informal meetings where you demonstrate the basic functions to stakeholders. We recommend, as much as possible, meeting with one group of stakeholders at a time. That way you can keep your conversations focused. If you have two different stakeholder groups represented and their expertise and interests are wildly different, you'll be boring ½ the participants all the time. Even if their expertise is similar, you may have groups with competing or conflicting requirements. While you need to understand such conflicting requirements and eventually come to some detente, this meeting is not the best venue for settling those issues; it would more likely simply scuttle your meeting and void any value from it.

After each meeting, review your requirements and see what more you need to add. Likely at such meetings, you'll begin to get requests for new features.

You have, in fact, begun the iterative process. Even the most bare-bones prototype that may only consist of a sequence of pictures is a first cut of your product. The sooner you can get to a running version, the sooner you will be able to respond to stakeholder suggestions by adding real features.