10.6 Installability Requirement Pattern

10.6 Installability Requirement Pattern

Basic Details

Related patterns:	None
Anticipated frequency:	Between zero and two requirements
Pattern classifications:	Affects database: Yes

Applicability

Use the installability requirement pattern to specify how easy it must be to install or upgrade the system (or a part of the system).

Discussion

Whenever you go to the trouble of building a system, it's handy to be able to install it. You can always rely on the developers to install it ad hoc somehow, and that can be acceptable if you're installing it in only one or two places. Something better is called for if (a) you want other people to be able to install it, (b) you'll have more than a handful of installations, (c) you can't afford an installation to go wrong, or (d) you don't want to give developers unfettered access to production machines. That's where installability requirements come in-to impose order on installation, to indicate how important installation is and how much trouble we're prepared to take, and as a reminder to allocate adequate resources to it.

The subject of installation is rarely mentioned in requirements. When it isn't, it's as if there were an implicit requirement that says "There shall be a way to install the system. It doesn't matter how unpleasant, time-consuming, unreliable, or insecure it is." Installation is often considered at all only when the (first) installation date draws near, but it deserves to be "on the radar" from the beginning. A common sentiment is, let's worry about installation when we've got a system to install. But that's not good enough. It often involves developing installation software and instructions, which should be treated just like any other software and documentation-and as an integral part of the system. Otherwise they'll be uncontrolled and under-scrutinized-and probably unbudgeted too.

The importance of good installability depends on how many installations there'll be (both discrete sites and number of machines in each site), which organization(s) will be doing them (yours or, if it's a product, a customer), the skills possessed by the installer, the complexity of the system, and the cost if it goes wrong. Installation is often the first a customer sees of a system in the flesh, and if it's awkward or frustrating it can create a negative impression that's very difficult to correct. They might even give up and decide not to install your system at all.

Write an installability requirement for each part of the system that will be installed independently-for example, server software and client software separately.

If you like, you can omit a requirement of this kind and specify only those specific installation features you want, as covered in the "Extra Requirements" subsection coming up.

Content

An installability requirement should contain:

1. Which part of the system (or all of it) Different parts of a system might be installed in different ways and at different times, although every part must be installed somehow (otherwise there's no point in having it). Write an installation requirement for each installable unit, and check that every piece of software belongs to one unit or another.

2. Who can install Who should be able to install this part of the system? What minimum level of skill should they need?

3. Ease of installation How easy must the software be to install? How smart should installation software be? Don't stray over the line into how the installation itself will happen-that is, its design. Don't go over the top either.

4. Installation medium (optionally) How do we put the stuff to install into the installer's hands? This is separate from preparing the installation bundle, and it can itself involve a reasonable amount of work. For example, if the software will be downloaded, we must set up a place from which to download it; if we're going to supply the software on CD, we must prepare installation CDs. Avoid mentioning particular media technologies as far as possible.

Template(s)

Open table as spreadsheet

Summary	Definition
«System part» installability	It shall be possible for the «System part» to be installed by a «Person who will install». «Ease of installation statement». [«Installation medium statement».]

Example(s)

Open table as spreadsheet

Summary	Definition
Client application installability	It shall be possible for the Web Shop client application to be installed by a typical customer who has no special expertise. The installation process shall be convenient and involve the entry of little information by the user. The client application shall be downloaded from the service's Web site.
Main system installability	It shall be possible for the system's main (server) software to be installed by a competent system administrator who has no previous knowledge of the system or of the third-party products it uses (but who is familiar with the operating system of the machines on which it is to be installed). The software shall be installed from a popular portable medium (such as a CD).

Extra Requirements

Installing a system is a complex business, especially if we don't want it to look complex. Consider the following additional aspects, and ask yourself whether they deserve their own requirements:

1. Installation instructions Even the simplest and easiest installation needs some instructions to tell an installer what to do. This constitutes documentation, so refer to the documentation requirement pattern (in Chapter 5), which has an example requirement for installation instructions.

2. Authorization to install Is possession of the installable software enough to install the system? If you're selling a product, you might want additional control, such as asking the installer to register the software or enter a license key allocated to them. Even if you allow anyone to install it, you might want to be notified each time it is installed.

3. Upgrading This is a special case of installing the system when a previous version is already installed. It has its own complications-and they tend to be neglected. See the "Upgrading" subsection in this pattern for further details.

4. Troubleshooting If something goes wrong during installation, provide ways for the installer (a person) to determine what the problem is and to fix it in as many cases as possible. If not, provide information they can pass on to an expert to assist them. Don't expect installation software to be able to figure out every difficulty, but ask for it to handle anything that has a reasonable chance of going wrong.

5. Security risks Sloppy installation can have security implications. Consider what they might be for your system, and write requirements to guard against them. For example, you might not want installation software lying around after it's been run (especially powerful general-purpose utilities). Or you could restrict an installer's access to sensitive data.

6. Training You might need to organize training for the people who will carry out installations, if you have enough of them.

7. Uninstalling Any piece of software that gets installed might one day need to be uninstalled. How easy it must be to uninstall a piece of software varies greatly depending on its nature. One usually expects a client or desktop application to have a properly packaged uninstall routine that will completely remove it at the click of a button. Expectations of server software are lower and typically nil for systems developed in-house. Write requirements for any uninstall demands you have. Write a separate requirement for each part of the system that has its own uninstall needs-for example, one for a client application and another for server software.

   Uninstalling an upgrade can be particularly troublesome (to the extent that it is sometimes impractical), so don't impose unreasonable requirements. For instance, if an upgrade involves converting data, it is normally not necessary to demand a reverse conversion process (because normally no one would need it).

Upgrading

We can expect a system to have several upgrades in its lifetime. (It better had-or it'll have a short life expectancy!) When specifying requirements for upgrading, we're not dealing with a particular upgrade but setting rules to be followed by all future upgrades.

The biggest question, when releasing a new version of a system, is: from which previous versions we must be able to upgrade to it? The answer depends on which versions are out there being used. Make sure the system is ready for every likely eventuality but don't go to the trouble of making provision for situations that, while conceivable, will never occur in practice in your environment. If you can, operationally, arrange for every site to upgrade whenever a new version is released; life will be simpler for everyone. Here's an example requirement to let us upgrade from any previous version:

Open table as spreadsheet

Summary	Definition
Upgrade from any previous version	When a new version of the main system is released, it shall be possible to upgrade to it from any previous version.

Instructions and software for upgrading are likely to be different from installing from scratch. They could be so different as to warrant separate instructions and software.

If an upgrade fails, do your utmost to allow the previous release to be still usable. Insist that the system be backed up before starting an upgrade.

It can be irritating when you've gone to a lot of trouble to tweak a system to suit you, only for an upgrade to set them all back to their defaults. If you want to avoid upsetting your users in this way, write a requirement to prevent it, such as this one:

Open table as spreadsheet

Summary	Definition
Upgrade not to affect configuration	Installing an upgrade shall not modify existing configuration values. An exception is made for any values that the new version uses in different ways from the previous version. The motivation for this requirement is to avoid wasting the time of users who have spent considerable time configuring the system to suit themselves.

Considerations for Development

Treat installation software as seriously as any other software, and treat it as a proper part of the system. Even if it's unsexy, it's still important. Automate as much as is cost-effective.

Create one or more utilities to check if a machine is ready to have the system installed: is there enough space, does it have the right operating system, are all required third-party products installed already, and are any other prerequisites met? Clearly explain every problem discovered.

Provide a reliable way of determining which version of the system is installed on each machine.

If you need to be able to upgrade to the latest version from any previous version, this can be achieved by a series of upgrades. For example, upgrading from version 1 to version 4 can be achieved by upgrading to 2 then 3 then 4. It's not necessary to properly install the software for in-between versions. We're talking mainly about information-related steps: creating database tables, converting data, and such like. This might be the easiest way to achieve upgrades from old versions, but it does mean that no installation software is ever short-lived; it's needed until every site has upgraded to a later version. But beware that upgrading via intermediate versions isn't always ideal. For example, if version 2 simplified some data (say, for performance) and version 3 restored the original complexity (because too much functionality was lost), upgrading from 1 to 3 via might cause loss of data that can be avoided if we go directly from 1 to 3. This might seem like a trivial matter to you, but it won't to users of the system.

If the system is installed on multiple machines, consider what might happen if some run one version of the system and some run another. If they reside in different locations, it might be impractical to upgrade them all at the same time, so you must arrange for old and new versions to run smoothly together.

Considerations for Testing

If installability is important enough to deserve requirements, it deserves to be tested properly, and that means going to the trouble of installing it from scratch purely to test how easy it is.

Test upgrades separately. Test the upgrading to a new version of the system from each previous version that is likely to happen in practice.

Ask the development team for a list of all the files that are loaded or created during the installation process and all the changes that are made to the environment of each machine by the installation. Check that installation makes the expected changes. See if you can detect any additional changes beyond those expected.

Beware of combinatorial explosion if you have several old versions, several machine environments (say, operating systems and/or databases), and several software components installed separately. Do all combinations work together? Does installation of the system work equally well in all cases? It's impossible to test all permutations, but you should prepare several different installation scenarios that together span every individual product and version that must be supported.

Test installation instructions at the same time as performing an installation-if there are instructions. If not, expect the installation to be self-explanatory. Do the same for an upgrade. Check that the instructions do this:

1. Describe prerequisites. These should explain everything you need before starting the installation and should list everything that should already be installed beforehand.

2. Adequately explain what the person installing needs to do.

3. Warn you against things you could easily do wrong during the installation.

4. State prompts and messages exactly as the installation itself presents them. If the instructions include sample screens, do they look the same as those displayed during the installation? Instructions that are even slightly incompatible can cause confusion.

5. Describe all the steps in the installation, in the same sequence.

Comprehensively testing installation also involves making mistakes. Draw a flow chart of the steps in the installation process and possible missteps. Consider things that could go wrong. What happens if an installation is abandoned before it finishes? Is it possible to restart it or to remove everything and try again? What happens if you try to install the system in an incorrect environment (for example, trying to use an unsupported version of the database, or with an essential third-party product missing)? Is the installation software smart enough to spot problems?

Test uninstalling the system. If there are requirements that cover uninstallation, test that it works to the degree and level of convenience demanded. If there are no such requirements, test whether uninstallation is practical. After uninstalling the system, verify that no traces of it remain (such as odd configuration files). Then reinstall the system as an extra check that the uninstall didn't leave anything behind.