10.3 Unparochialness Requirement Pattern

10.3 Unparochialness Requirement Pattern

Basic Details

Related patterns:	Multiness, data type, extendability
Anticipated frequency:	One requirement per aspect, with extra requirements for the implications
Pattern classifications:	None

Applicability

Use the unparochialness requirement pattern to specify a particular way in which the system must not be limited to one business environment. The unparochialness requirement pattern says how a single installation of the system needs to be able to adapt to the organization and the place where it is installed.

Do not use the unparochialness requirement pattern to specify that the system must support multiple instances of anything simultaneously (such as multiple currencies); use the multiness requirement pattern, the next pattern in this chapter, for that.

Discussion

Parochial: narrow in outlook or scope, merely local. So says the dictionary. If you build a system for one organization, that's what you'll get-no more, no less. Don't assume it'll suit any other organization, even one down the road that's in the same business. It's unreasonable to expect otherwise, unless you expressly insist. Yet companies sometimes do: executives impressed by their new system have the bright idea of making money by selling it. But they're probably in for an unpleasant surprise if suitable provisions weren't made in the first place-which is where unparochialness requirements come in.

When building a product or a system for multiple sites, it must suit each of the environments in which it will be installed-or, at least, the system will be much better received (and, for a product, more competitive) if it's not obviously been built for someone else, somewhere else, or for a different market. But also take sensible steps to make a system amenable to installation in other environments it might encounter, without lots of rework, because adding it all later is invariably much harder than incorporating it from the outset.

Look beyond the narrow confines of a single target environment. It's natural for analysts and developers to specify and build systems that they, the customer, and the people they know would like to use-systems for us-and in the main it makes systems more friendly, more complete, and more sensible. But we can't allow this inclination to be our only guide, because we'll then get a system built just for us. People aren't intentionally parochial; when they're parochial, they are without thinking about it. Requirements to make systems less parochial are scarcer than they should be, which probably contributes significantly to systems being harder to implement successfully outside their home environment. This requirement pattern aims to prompt analysts to write requirements on this topic when they otherwise wouldn't.

Specifying unparochialness is a two-stage process. First, identify everywhere the system might be installed-not as a detailed list of installations, but in broad terms. Second, figure out what sorts of variation from one installation to another is needed to accommodate them all. The rest of this section covers the first stage, and the second stage is dealt with in the "Extra Requirements" subsection coming up.

Write an unparochialness requirement to sum up the scope of prospective installations-a statement of what we have in mind (such as selling to other companies in the same business in the same country). Then, write more detailed requirements to spell out what that really means in terms of specific ways in which the system shouldn't be tied down. But once we have the detailed requirements, the original requirement can be dropped-or demoted to being an introductory statement rather than a formal requirement. In a two-level hierarchy of requirements, the original unparochialness requirement equates to a high-level business requirement, and the rest are detailed requirements.

The first step, then, is to consider where the system might be installed. The most common possibilities are these:

• Single site If it's a system for one site only (say, for internal use), can you be sure it'll never be installed anywhere else? If you believe you are sure, state it explicitly as an assumption-both to spur any reader with grander ideas to speak up, and to defend against possible accusations of inflexibility in the future.

• Different sites If it's to be installed in multiple sites-or departments or operating units-belonging to the same organization, how diverse are they? What differs from one to another?

• Different organizations Is it possible that the system will be installed by other organizations? If so, in what ways could their business practices be different? Answering this question usually involves serious investigation. If you assume everyone does things the same way, you're likely to be wrong. Even an expert in this business area who assumes that is likely to be wrong.

• Different industries If you're building a system for use in one industry but would like to extend its use to others, what do they do differently? Fundamentally the industries might be very similar yet still vary in minor details (such as terminology used).

• Different countries and regions Even the most cubicle-bound recluse is aware that other countries speak different languages and use different currencies, but they also do lots of other things differently. What things must our system worry about? The "Extra Requirements" subsection discusses a few. But that doesn't mean the system needs to adapt to every local difference. An overseas subsidiary might be accustomed to working in our language and quite happy to use our system in its original language.

It's worth repeating that we're just talking about tailoring the whole system to suit its local environment-not catering for multiple variations at the same time, which is what the multiness requirement pattern is for. For example, one installation being able to support users from multiple countries at the same time-in multiple languages, multiple currencies, and so on-involves a lot more than just avoiding a parochial outlook. Variable single-thing is not the same as multi-thing. A system that allows its base currency to be configured is definitely not automatically multi-currency.

Don't go overboard, though. Don't demand things that are likely to be expensive to implement but have a low chance of being needed (because they're speculative or no more than a gleam in someone's eye). Also, some things. such as data types, are so fundamental that allowing them to vary from one installation to another is just too hard.

Temporal Parochialness

The rest of this requirement pattern deals with where a system is suitable to be used, but there's also the subject of when. Don't limit a system to working only during a certain time period.

Y2K is the most blatant example of systems demonstrating temporal inflexibility-and it's hard not to regard this inexcusable short-sightedness as a case of mass parochialness. It's easy to view Y2K as a software development failure, but plainly there were no requirements specified to prevent it. It might be a long time before we need to worry about Y2100 (or Y2.1K or Y21C, or whatever it'll be called), but one or two opportunities might arise before then for systems to stumble upon an artificial date beyond which they won't work properly. The last example requirement in this pattern aims to be a catch-all against all potential problems of this kind; it should not be necessary for requirements to identify specific pitfalls.

Beware! The people who brought us Y2K are still out there (or, at least, their next generation are), poised to inflict further parochialnesses upon us-in both space and time-if we let them.

Content

An unparochialness requirement should convey:

1. Suitability conditions How broad (and how limited) is the set of environments for which the system should be suitable? Be as specific as you can. If it might be installed in other countries but only in one continent (say, Europe), point that out. It might help the developers to know it won't be installed anywhere with a language that needs a multi-byte character set (as in much of Asia).

2. Motivation Why do we want the system to be installable in these different environments? For example, we might want to sell the system there, or perhaps the company has offices there. If these are only secondary goals and the first installation is what we're really building the system for, say so in order to put this requirement into perspective.

3. Example variations What are the implications of needing to install the system in this range of environments? Give some examples of the sorts of variation from one installation to another that's needed (such a different base currency).

Template(s)

Open table as spreadsheet

Summary	Definition
Not specific to «Single environment name»	The system shall be suitable for use by any organization that «Suitability conditions». «Motivation statement». For example, «Aspect variation statement(s)».

Example(s)

Open table as spreadsheet

Summary	Definition
Not specific to Acme	The system shall be suitable for use by any company in the same line of business, following the same business practices and residing in the same state as Acme Corporation. The motivation is to permit the sale of this system to similar businesses, though it must be recognized that the system is primarily for internal use by Acme Corporation. For example, the name "Acme Corporation Inc." and similar text values must not be hard-coded anywhere.
Suitable for Acme offices worldwide	The system shall be suitable for use by any Acme Corporation office in any country in which Acme operates. It is assumed that all users of the system speak English, so translation into other languages of the system's user interface, reports, documentation, and other materials is not necessary. Acme has offices in North and South America, Europe, and Asia.
Not specific to U.S.	There shall be nothing in the system that ties its use to the United States. For example, the local currency must not be fixed to be U.S. Dollars.

The following requirement aims to be a guard against temporal parochialness for all time:

Open table as spreadsheet

Summary	Definition
No time restrictions	There shall be nothing about the system to prevent it being used for an arbitrarily long period (decades) into the future. That is, there shall exist no date beyond which the system shall cease to work normally. The motivation of this requirement is to prevent anything equivalent to Y2K problems.

Extra Requirements

Assuming we've identified (as in the preceding sections) the range of environments in which our system is liable to be installed, we now come to stage two: specifying the implications, in the form of all the possible types of variation from one installation to another. How can we work out in which ways other places do things differently? This can involve considerable investigation. This general purpose requirement pattern can't delve into matters that are specific to a particular organization or industry. But it can mention a number of things that can vary from country to country and common ways in which organizations vary-and it does so in the following two subsections.

One last extra requirement that might be worthwhile is to demand that the system's documentation not be parochial. Here's an example of such a requirement:

Open table as spreadsheet

Summary

Definition

Documentation suitable for all installations

All documentation produced for the system shall be suitable for use by and readily understandable by any organization and in any country in which the system is liable to be installed (as per requirement XR19). In particular, no documentation for the system shall contain confidential Acme information. This requirement does not, however, extend to foreign languages: documentation only in English is satisfactory (though it does not preclude other requirements stipulating documentation in other languages).

Differences between Countries

Here is a range of things that vary from one country to another, with some resulting complications mentioned:

1. Currency Switching a system's base currency (the one all monetary amounts are taken to be denominated in) can take more than just nominating a different one to use. It can affect the number of decimal places to which to display monetary amounts: not all currencies use two. If you have both a company base currency and a local currency, you might need to worry which way round exchange rates are quoted (for example, it's Yen to the U.S. Dollar, but U.S. Dollars to the Pound).

2. Numeric display format The primary differences are in the symbols used for decimal points and thousand separators. Also, the thousand separators aren't put between the thousands in all countries (viz India with its 99,99,99,999 format made up of lakhs and crores and so on).

3. Date display formats Is 1/4 the 4^th January or 1^st April? Simply allowing the system to conform to the local convention might not be enough to avoid confusion. For example, a report for head office might use a format different to that used in a local office that produces it. If there's any risk of confusion, you could add a requirement that the date format be explained explicitly wherever dates are shown.

4. Language It's a large undertaking to translate a whole system into another language. If you want to make the system amenable to being used in a place with a different language, some of the things to consider include:

   1. Ban the hard-coding of all language-specific text, including error messages, menu contents, and other fragments for display to users. If yours is a Web-based system, don't assume the whole user interface is defined in HTML pages themselves.

   2. Text isn't the only medium that can be language-specific: the content of images, audio, and video can be too.

   3. Some languages (such as Chinese) require a multi-byte character set.

   4. Some countries (such as Canada and Switzerland) have multiple official languages.

   5. Keyboard layouts can vary, often to accommodate characters with accents or different alphabets.

   6. A user could be running their operating system and other products in another language, even if your system is monolingual. So, wherever possible, avoid making assumptions about the names, prompts, and message texts that other software presents to the user. This applies mainly to user guides, help pages, and other documentation.

5. Dialect Just because another country speaks the same language as you do, don't assume they say or spell everything the same or will understand the same colloquialisms (say, from sports popular in your country but not in others). If possible, use words that are spelled the same in all dialects. For example, "bookmark" is preferable to "favorite" because it avoids inflicting the American spelling of the latter on speakers of British English. This book takes trouble to talk about "how systems behave" rather than "their behavior/behaviour" for the same reason (except when it's awkward to do so).

6. Time zone Bear in mind that not all time zones vary from one another in whole-hour increments. Daylight saving time varies: it doesn't start or end on the same date everywhere; some countries don't have it at all; and when clocks go forward in the Northern hemisphere, they go back in the Southern (and vice versa).

7. Financial year The date on which the financial year ends varies from country to country.

8. Calendar The working days of the week aren't the same everywhere. Public holidays are not necessarily countrywide (and of course they vary from country to country). Public holidays can be for a full day or for a half-day only. The Gregorian calendar is in practice the international standard, and commercial systems rarely need to deal with any other, but it's not the only one in day-to-day use. Some businesses, especially in Europe, use the ISO calendar (defined by the ISO 8601 standard), which states the day number in the calendar year instead of the month and day-in-month.

9. Geographic regions Countries divide themselves up in different ways: states, territories, provinces, counties (and those are just in English-speaking countries).

10. Post codes Some countries use simple numbers; some use more complex schemes.

11. Address formats Even beyond region and post code differences, countries vary in how they conventionally display addresses.

12. Telephone numbers The number of digits and the usual placement of separators vary.

13. Measurement system Metric or that other one, whose very name varies between countries. In the U.S., it's called U.S. or English; in England, it's called Imperial. Plus, a country might use metric for some units but not for others.

14. Punctuation Which characters should be used for quotes, question marks, exclamation marks, and so on?

15. Cultural differences For example, images that are acceptable (even innocuous) in one culture might not be tolerated in another.

16. The country itself We don't want the name of the local country itself to be fixed-or for the system to assume, in some hard-coded way, that it knows which country it's in.

This isn't a comprehensive list. It ignores areas that differ functionally from one place to another, such as tax, regulatory, and legal regimes. (Some of these differences can be dealt with by using the extendability requirement pattern we saw earlier in this chapter.) Ways of doing calculations could also vary-for example, bank interest calculations. (See the fee/tax requirement pattern in Chapter 12, "Commercial Requirement Patterns," and the calculation formula requirement pattern in Chapter 6, "Information Requirement Patterns.") It also ignores variations that are usually of no concern to systems but that just might affect yours, such as national flag, continent, and hemisphere.

You're unlikely to need to worry about all of these things, but run through this list asking yourself whether each one is relevant.

Differences between Organizations

Organizations differ from one another in numerous ways, even in the same industry, and it's impossible to do more than scratch the surface here. But you might want to consider these few common topics:

1. Data types Our company might use numeric codes for something; another company might use 3-character strings. It's usually impractical to switch from one data type to another, so avoid writing a requirement for the system to be able to. But you could consider adopting data types that are more flexible, such as strings rather than numbers.

2. Organization structure Our company might have a two-level hierarchy of operational units; another company might have four. Take steps to accommodate the more complicated structures the system is likely to encounter. (See the multi-organization unit requirement pattern in Chapter 12 for more.)

3. Employee roles It's always good practice to make employee roles configurable-if nothing else, to cater for change in our own organization. But it's more important if the system's going to be installed elsewhere. (See the access control requirement patterns in Chapter 11 for more.)

4. Accounting entries If your system generates information for use by an accounting system, consider whether it's tied too closely to how your own organization performs its accounting.

5. External systems For each external system our system connects to (via an inter-system interface), another organization might be running a different system. Make it as easy as possible to slot in a different inter-system interface (as per the extendability requirement pattern discussed previously in this chapter). If you interface to an external system for more than one purpose, another organization might use separate systems for each of them. In this case, it's better to treat each purpose as a distinct inter-system interface.

6. Terminology One company might use different names for certain things.

Considerations for Development

Treat an unparochialness requirement like an instruction not to hard-code this area. That advice doesn't apply in every case: some things need different code to be called in different installations, which means allowing code to be plugged in (as described in the extendability requirement pattern covered earlier).

Considerations for Testing

Properly testing that a system is suitable for installation in the range of places demanded is a major undertaking. A reasonable simplification is to envisage two installations that differ from each other in every possible way. If we have a primary installation, it will be one; make the other as different as you can. This simplification still means we need two full test implementations of the system. If you don't want to go that far, perhaps because secondary installations are a low priority, perform one full pass plus a targeted set of spot checks for selected alternative values. Or try "anecdotal" checking: ask developers what they've done to satisfy the unparochialness requirements, read the documentation for signs that variations are catered for, and run configuration functions to see whether they allow the relevant base values to be changed.