1998, Softbound, 448 pages
ISBN 1884777597
Sample Chapter 15
© Mannning Publications Co. All Rights Reserved.
acronyms "affect/effect" "always" assumptions
"click on" "compose/comprise" conventions "correct"
cross-references "data" definitions dependencies
document titles "entry" fancy cover first sentence
glossary "i.e./e.g." "invalid" metatext
"model" page layout "paradigm" "represents"
requirement statements tables title page "type"
underlining
"use"
"valid"
voice
A good document organization and wise choice of content are only as effective
as the small details that fill out that organization and present that content.
This chapter is a collection of short articles covering a wide range of small
details of technical writing that often come up when writing software
requirements and specifications. Some of the articles are about individual
words. These are marked by headings in quotation marks. Others cover the basics
of broader topics, such as, how to make useful
TABLES and how to write a
DEFINITION.
Whenever possible, try to avoid inventing new acronyms. They're opaque to the uninitiated, and, of course, you're writing for the uninitiated. They take a person a lot longer to learn than a word or a two-word phrase. However, if an acronym is already part of the vocabulary of the problem domain, then you must explain it in the requirements document.
The meaning of an acronym is seldom made clear by indicating what its letters stand for. If you know that OSS stands for "operations support system," do you know what an OSS is? For more information, see DEFINITIONS and GLOSSARIES.
Words easily confused. Affect is most often a verb, and effect most often a noun:
Affecting something is causing an effect within it.
Adding to the confusion are a noun usage of affect , having a completely unrelated meaning, and a verb usage of effect , meaning "make" or "bring about." Fortunately, these additional senses are seldom needed in technical documents.
It is sometimes claimed that a requirement should never assert that something is to always or never happen. For example, a requirement should not say that the system should always reject an order from a customer on credit hold. This is because a requirement is supposed to be finite, and an "always"or "never" statement pertains to a potentially infinite amount of time. The reason for wanting requirements to be finite is because requirements are supposed to be testable, and it's impossible to test an infinity of cases.
This is a mistake. Test cases are necessarily finite. You test a system, say, for three weeks. The purpose of testing is not to determine that the system worked for three weeks. The purpose of testing is to either gather evidence that supports an inference that the system will meet requirements indefinitely far into the future, or to uncover evidence that it won't. Testing is always imperfect. Even finite requirements that have a mere quadrillion possible cases (many fewer than in most real-world system) are impossible to test one by one. Testers carefully choose their test cases to expose evidence that has as much logical leverage as possible, to learn as much as possible about how the system will perform during the potentially infinite span of time when it is not being tested.
Furthermore, the people who design specifications and write programs are not trying to produce a system that works only during testing. The problem they are trying to solve is, "How can we make such-and-such always happen?" The requirements document should state that problem and not confuse it with the separate problem of how to verify that the software meets the requirements.
To put it another way, the customer will be somewhat nonplussed if you write that the cutting blade will not fall while a person is in the cutting area--but only during the first three weeks of operation.
The word assumption , like its frequent companion DEPENDENCY, is vague. There are a wide variety of things in software development that are equally well named by the word assumption , so you can never safely--ahem--assume that the reader will understand the one that you intended, without providing some clarification.
Faced with a template containing a section named Assumptions, it can be tempting to include anything you can think of, only for the sake of having something to include in that section:
| 1.8 Assumptions
This document assumes that DEX will be developed according to XYZ Corporation Software Development Standards, doc. no. 045-71001. |
And what if the staff does not develop the software according to XYZ Corporation Software Development Standards? What useful information does this sentence communicate to the reader? Since it communicates nothing, it should be deleted.
Assumptions worth stating are those where you can identify something in the document that would have to be changed if the assumption were changed. Identifying an assumption is useful only if you explicitly indicate what would have to be changed.
For example:
| This user interface is designed on the assumption that it will be implemented in Visual Basic. If we switch to a different tool, we would probably need to change the appearance and functionality of a number of the controls. |
It's neither necessary nor possible to state exactly which controls would have to be changed, without redesigning the user interface for every other available tool. But even though this paragraph doesn't go into detail, it communicates useful information to the reader. If a programmer is considering switching to a different tool, they will be on the alert for user-interface decisions that exploit capabilities of Visual Basic that are not available in the new tool. If a user-interface designer is considering a different tool, they will also be on the alert for compromises made in response to the limitations of Visual Basic that don't need to be made with the new tool.
Notice that this definition of assumption includes all problem-domain information. If the objects in the problem domain have different attributes than those you describe, or if events can come in different sequences than those you describe, then, of course, you would change the document. The majority of a good requirements document is problem-domain description, but there's no need to call it "assumptions." Reserve this word only for specific assumptions about the development process on which you have premised some of the decisions expressed in the requirements document or specification.
A small improvement, to decrease wordiness, is to consistently write that a user "clicks" an object rather than "clicks on" an object.
Two surprisingly tricky words that occur often in requirements. The standard usages are:
The whole comprises the parts.
The parts compose the whole.
The whole is composed of the parts.
Comprise , in other words, means to encompass, or include. Compose means to fit together to form something larger, like the way that musical notes together form a musical composition.
Therefore the digits do not comprise the identification code, but they do compose the identification code. The identification code is not comprised of digits (a nonsensical phrase), but it is composed of digits, and, to say the same thing, it also comprises the digits.
With such a subtlety of English usage, it may be most prudent to abandon tradition and simply treat these words as synonyms. Fewer and fewer people know or care about the difference, anyway.
A better solution is to not word a sentence in such a way that a reader's ignorance of the distinction could lead them to misunderstand. One way to do that is by always providing redundant clues indicating which word you intend as the whole and which you intend as the parts. This is very easy because, as in "digits" and "identification code", the whole is normally singular and the parts are normally plural.
Another way to avoid the confusion is by using different words altogether, like consists of:
| The identification code consists of 9 hexadecimal digits. |
The simple word is is often even better:
| The identification code is a series of 9 hexadecimal digits. |
Includes and contains are poor substitutes, since they suggest that more might be included than what you list. "The identification code includes 9 hexadecimal digits." And what else does it include?
The following text demonstrates both some recommended typographical conventions and a good way to describe them:
| This document observes the following typographical conventions.
Requirements are testable effects or conditions to be created by GEO: services to be provided to users, rules to be enforced, etc. Requirements are written in bold sans serif type and given an identification number preceded by an R. For example:
Data to be stored by GEO is written in sans serif type, to distinguish it from real-world objects and attributes that it represents. For example: a structure is an outdoor object, such as a telephone pole or building, to which cables can connect; but a structure is a collection of data stored in the GEO database about a structure. A structure type is one of the pieces of data in that collection. Named data values are written in italic sans serif type. For example, the possible values of structure type are: pole, pedestal, building, manhole. String literals--alphanumeric data to go into the system exactly as shown, such as filenames--are written in sans serif type. Program code is written in the Courier font. Names of windows and controls are written in italic sans serif type. Preferences are evaluation criteria for choosing between two or more designs that meet the requirements. There's no way to test a preference; a preference only provides guidance in making the most useful possible design. Preferences are written in bold sans serif type and given an identification number preceded by a P. For example:
Invariants are conditions that are not to be changed by any event, or by a specified set of events, though they might be changed temporarily during the event. Invariants are a redundant check on the correctness of the requirements. If any requirements describe an operation or possible sequence of operations that could result in an invariant being violated, the requirements are incorrect. Invariants are written in bold sans serif type and given an identification number preceded by a V. For example:
|
Notice that all of the examples to illustrate the conventions are taken from later in the document, and the name of the software--GEO--is mentioned explicitly, instead of a generic term like "the system."
Naturally, omit any paragraphs for conventions that don't apply to the document that you're writing. You may well omit the entire discussion of the conventions, if you're sure that your readers don't need to have them explained. Good typographical conventions are intuitive enough that they really need no explanation, though the above text also provides a place to explain the concepts of requirement, preference, and invariant, which might be unfamiliar to many readers. Even if you include the section explaining the typographical conventions, you should still strive to write the remainder of the text so that someone could understand it without having read the discussion of the conventions. Most readers skip that section anyway.
There is a little bit more to the conventions that a reader does not need to know, but that you need to know when writing the document:
| Landbase filenames have the format lbxxxyyy.dwg, where xxx and yyy are the x and y coordinates of the upper left corner of the map, respectively. |
The convention of writing requirements, preferences, and invariants in bold sans serif type, putting them on separate lines from the rest of the text, and putting the identification numbers in the left margin, makes it easy for a reader to scan through the document looking for "just the meat." This way, you can add commentary to each requirement without the extra text camouflaging the requirement statement.
The reason for the convention of putting variables in italic serif type even when inside sans serif text is that italic sans serif text does not stand out very well. For example, in lbxxxyyy.dwg, the coordinates do not stand out nearly as well as when they're written in the serif font.
Similar remarks as for INVALID.
If you find yourself needing to repeat something explained at length elsewhere in the document, keep in mind that, instead of repeating it, you can refer to it by page number or section number. Cross-references are an indispensible weapon against the temptation to say everything in one sentence, bore the reader through repetition, or create a jigsaw puzzle. [1]
When you make a cross-reference, be sure to include the page number or section number explicitly, via a special instruction to the word processor, rather than write "the following section" or "above." Later, you might insert another section, necessitating that you change the cross reference to "two sections below" or "two sections before this one." If you let the word processor fill in the page number or section number automatically, you won't have this problem.
There's nothing wrong with referring forward in the document. The ideas in a requirements document or specification are usually so interconnected that there's no way to avoid forward references.
Some grammarians and editors insist that you treat the word data as a plural noun because it's a borrowing from Latin, where it's the plural of datum. For example, they'd insist that you reword "This data represents the pH of the aquarium" to "These data represent the pH of the aquarium."
However, usage in computers has established a singular meaning of data , which has proven too convenient to abandon because of etymology. Most people today don't even know the connection with datum , and when trying to follow the rule " data is plural," have often fouled up otherwise readable sentences for lack of a singular. If you're editing someone else's document, don't push this obsolete rule.
To indicate plurality, write "types of data" or "sets of data."
A definition is a statement that identifies what a concept refers to, by identifying the concept's location in the conceptual framework of which it is a part. A proper definition achieves this by indicating the broader concept, called the genus (plural: genera ), of which the concept being defined is a special case, and one or more distinguishing characteristics, called differentiae (singular: differentia ), that distinguish the concept from others of its genus.
Some typical definitions:
A common temptation when writing a definition is to omit the genus. This results in an unclear definition because, often, a reader can't infer the genus and consequently can't tell what kind of thing you're talking about. Definitions that are phrased "is when" or "is where" almost always omit the genus, and are almost always unclear.
| Missing Genus | Clearer |
| A compiler translates source code into machine language.
What performs this translation? A computer? A person? If you're writing for someone who doesn't know what a compiler is, you can't expect him to know that it's a kind of program. |
A compiler is a program that translates source code into machine language. |
| An overplot is when two things overlap.
An overplot is not a point in time, but this definition seems to say that it is. |
An overplot is an overlap between two or more graphic entities drawn at the same place on a page. |
| HC: Identifies the house count at a telephone pole.
This definition makes a reader ask what thing does the identifying. In fact, nothing does; see the definition at right. |
HC: The number of houses that connect to a single telephone pole: "house count." |
Notice that a definition is much more than a synonym for a word. A definition indicates a way of mentally dividing reality for purposes of talking and thinking about it. Italicizing the word or phrase for the concept being defined is a helpful cue to the reader to interpret the sentence as a description of a named mental distinction, rather than an assertion about the things included within that distinction.
A circular definition is one that includes the concept to be defined in the genus or differentia. Of course this is illegitimate, because the definition is meant to communicate a concept to someone who doesn't already know it. A definition draws upon the reader's knowledge of all the concepts in the genus and differentia to help the reader form a new distinction.
This does not imply, however, that the words that describe the genus or differentia can't be among the words that name the concept to be defined. For example, the following is a perfectly good definition:
A patron request is a request made by a patron for a bibliographic item, without specifying the lending institution from which the bibliographic item is to be retrieved.
The fact that the name of the concept being defined is patron request does not mean that there's anything wrong with referring to patrons and requests in the definition. A patron request is a certain kind of request, and what (partly) distinguishes it from other types of requests is the fact that a patron makes it. Many made-up terms contain their genus and differentia within them; that's what makes them self-explanatory terms.
Here are some helpful genera for tricky definitions: the act of, a method of, the responsibility to, a commitment to, a set of, a type of x that, information about, facts about, the amount of, the number of, a measure of, the ratio between. A few examples:
| Final post is the act of permanently recording all additions,
deletions, and changes made to physical plant, once all work on a work print has
been completed.
A booking is the commitment of a seat on a specific flight and day to a specific passenger. dBmV is a measure of the voltage level of a signal, equal to 20 log10 mV, where mV is the number of millivolts measured across a resistance of 75 ohms. |
Some concepts are actually tuples--that is, groups of two or more kinds of things mentally grouped together. Since you probably don't want to have to define the concept tuple, you can give the genus as combination, as in "a problem is a combination of data, an unknown, and a condition relating the unknown to the data." [2]
When defining an attribute, often it helps to write "said of" to indicate the type of thing that the attribute applies to. In this case, you don't need to explicitly state the genus as "attribute of entity-type x." The same technique is sometimes helpful when defining relations and actions, too. For example:
| aerial: Suspended from poles or similar overhead structures; said of cable,
strand, anything that can be hung from poles.
attenuate: To decrease in strength; said of a signal passing through a transmission medium. |
The above is a typical format for a definition in a GLOSSARY: the term to be defined at the left, and just the defining information at right, instead of a complete sentence. If you were to include the aerial definition inside a narrative paragraph, you could word it this way:
| Cable or strand is said to be aerial if it is suspended from poles or other overhead structures. |
Some concepts are too fundamental to be defined: they don't have a genus, or there are no concepts to relate them to others of the same genus. Examples are: entity, attribute, relation, action, event, state, quantity, quality, point in time, type. Some concepts, like record, field, responsibility, commitment, program, and data, do have definitions, but they require more theoretical discussion than you probably want to include in a requirements document. You seldom need to communicate the meaning of such a term, but if you do, don't try to give it a proper definition. You may have to rely on synonyms; better yet, give an example that guides the reader to see how the concept is abstracted. For example, "Entities are objects that possess attributes, engage in actions, or participate in relations, as a person has height and weight, can travel from one place to another, and can be the parent, sibling, or child of another person."
Other concepts are difficult to define because we form the distinction perceptually. Who, other than a biologist, can define tomato? We distinguish tomatoes from other foods by appearance, not by an easily verbalizable relation with other concepts. Fortunately, there is almost no need to define such concepts. It's enough to say "a type of vegetable" (or "a type of fruit" if any biologists are around); that is, provide the genus but skip the differentia. If you must indicate to a reader enough information to help him recognize a plant or other visually distinguished type of object, then provide a picture.
To define a particular kind of state or status , list the complete set of mutually exclusive states. For example, "A proposal's approval status is its current stage in the process for granting or denying it: awaiting department approval, awaiting chair approval, awaiting board approval, or denied." The word current is helpful when defining states.
Some concepts are distinguished only by their level in a hierarchy. For example, a typical copper-wire telephone network has three levels of cables: feeder cables, distribution cables, and drop cables. Obviously, a good genus to define these concepts is cable or cable in a copper-wire telephone network, but differentiae like top-level, mid-level, and bottom-level would not communicate much. There are two solutions here: define each cable by the things that it connects to, and draw a picture.
| Wirecenter: the geographical area served by a single central office.
Central office: a building where local call switching takes place. Main distribution frame: a large connector at a central office, which connects the switching equipment to feeder cables. Feeder cable: a large cable that connects to the main distribution frame at a central office and feeds into distribution cables. Distribution cable: a cable that connects between a feeder cable and one or more terminals.
Drop cable: a small, usually two-pair cable that connects between a terminal and the connector box at a subscriber's building. (Remaining definitions omitted.) |
As this last example illustrates, concepts often come in groups where each concept is distinguished by its relation to the others. A diagram that simultaneously depicts all of them is an indispensible way to help a reader grasp each distinction, much better than words alone can. If you bombard the reader with a series of terms and definitions--wirecenter, central office, call switching, main distribution frame, feeder cable, distribution cable, drop cable, terminal, dead end, and cross connect--he can't possibly retain it all. The diagram presents the same number of concepts without being overwhelming. A reader can refer to it many times while reading the text, each time able to see how each concept relates to all the others, not just to the one or two listed in each definition.
The word dependency is vague. There are many ways in which one thing can depend on another. So, as when writing about ASSUMPTIONS, you must be explicit:
| Vague | Explicit | |
|
XYZ depends on the following software: |
The following software must be complete before programmers at ABC Corp. can begin developing XYZ: | |
|
XYZ depends on the following software: |
The following software must be installed on any computer on which XYZ is to run: |
Don't say that the customer cannot depend on the software to generate correct results if the users don't carry out the operating procedures as described in the specification or user's manual. If you're going to say that, you might as well say that the customer can't depend on the software if the users make random patches to the executable file. See "Writing for the hostile reader" in section 13.4.
The title of a document should be clear and terse, instantly informing potential readers of its content and purpose. Shown below are some ways to improve common document titles:
|
Wordy, unclear, or confusing |
Direct |
|---|---|
|
XYZ SRS XYZ Software Requirements Specification XYZ Requirements Specification XYZ Requirements Specifications XYZ Detailed Functional Requirements Specifications Document (DFRSD) |
XYZ Requirements |
|
XYZ High-Level Requirements |
XYZ Preliminary Sketch or Preliminary Sketch of XYZ Requirements The reason for this change in wording is to avoid suggesting a higher degree of rigor or commitment than a "high-level requirements" document actually delivers. Calling it "preliminary" is also an invitation for wide-ranging comments and suggestions. |
|
XYZ Functional Specification XYZ Functional Requirements |
XYZ Specification or XYZ Program Specification |
|
XYZ Logical Data Entities and Attributes |
XYZ Data Dictionary |
|
XYZ User Interface Requirements |
XYZ User Interface or XYZ User-Interface Design |
|
XYZ External Interface Requirements |
XYZ/ABC Interface or XYZ/ABC Interface Design or Interface Between XYZ and ABC An important improvement here is that ABC is mentioned explicitly in the title. |
|
XYZ Guidebook to Terminology and Nomenclature |
XYZ Glossary |
See also TITLE PAGE.
Can denote either the act of entering, or an item in a list. In the latter sense, entry is usually awkward and confusing. Try substituting item or element. For example, a pull-down menu contains "items," not "entries."
A requirements or specification document is scaffolding. Especially before customer signoff, it's incomplete, not fully thought through, and continuing to change as the result of reader feedback. The appearance of the document should reflect this.
If the purely cosmetic details of the document are too refined, such as a fancy, glossy cover, or an artistic typeface, the document sends a different message to its reader. It leads the reader to understand that it contains the final, perfected result of the best expertise your company has to offer. Consequently, any flaw, such as missing details about the customer's business processes, a section that's hard to understand, or grammatical or spelling errors tends to be seen as a reflection on your level of competence. You probably don't want a customer to take that attitude toward your document. The customer should see flaws not as reasons to reconsider the deal, but as opportunities to help improve the software, and as a normal, expected part of the design process.
These documents should certainly be as professional and readable as you can make them, but it's unwise to polish their appearance. Stapling the document or putting it in an old, three-ring binder is good enough.
The first sentence of a requirements document should tell the reader what thing the requirements pertain to--the piece of software to be developed. The structure of this first sentence should follow the same principles as a DEFINITION. For example, the very beginning of a document titled GEO Requirements might read
| 1.1 Overview
GEO is a program to allow users to add x, y coordinates to objects stored in the DBG database. |
This sentence tells the reader what the document is about: GEO. The rest of the paragraph might describe the DBG database, x, y coordinates, and the sorts of objects stored in the DBG database. It's almost always worthwhile to supplement this opening description with a very simple block diagram--perhaps a diagram derived from the frame diagram you made while thinking through the requirements, or the frame diagram itself. Now the reader knows what you're talking about, and you can start making statements about GEO: its problem domain, its requirements, the platform it's supposed to run on, and so on.
The thing that the requirements are about is the single most important, most fundamental piece of information to include in a requirements document. That's why it should come first. Yet this information is often entirely omitted from requirements documents, in favor of a useless "purpose and scope" section, like this one:
| 1.1 Purpose and Scope
The purpose of this document is to describe the requirements for GEO. |
Notice the difference between this sentence and the one recommended above. The "purpose" sentence communicates nothing that wasn't already clear from the title of the document. If the reader did not already know what GEO is, this sentence doesn't help.
The recommended sentence gives the reader new information: it answers the question, "What is GEO?" Without an answer to that question, the reader will have a very hard time understanding the rest of the document. A little later on the page, once you've introduced all the main concepts, you can spell out details such as which version of the software the document applies to. (This information should also be on the TITLE PAGE.)
Since you're defining a particular thing rather than a concept, finding the genus can be tricky; you have a lot of options. Fortunately, almost all of them are good. Here are some helpful genera to choose from: program, software, piece of software, software package, library, API, database, system.
More example first sentences:
| Labcon is a C++ library for controlling laboratory instruments
manufactured by Exsys, Inc.
Erasmus is a full-text database of medieval literature. VERBIS is a software package to track all aspects of a human-resources department: fringe benefits, vacation time, job postings, job descriptions, employee skills, company organization, and employee training. The Mensis 2000 is a court-reporting machine: a machine to enable court reporters to transcribe courtroom conversation and print it out word-for-word later. This document describes the requirements for the software inside the Mensis 2000. |
Italicizing the name of the product further indicates that the sentence is the definitive, fundamental statement of what the product is.
The last example ends with a sentence similar to the "purpose" sentence, with the difference that the preceding sentence renders it meaningful, by describing the machine that the software is a part of. This strategy of "describe the machine first, then say that this document describes the software for the machine" is suitable for most embedded applications, where the software has no name of its own.
In a glossary, place each term in the left margin (see PAGE LAYOUT), as it would appear in the middle of a sentence. That is, write the term in lower case unless it's always capitalized. If you capitalize all the terms, the reader won't know whether to capitalize them in the middle of a sentence. Put the terms in bold sans serif type, to make them easy for a reader to scan through when searching for a specific term.
Write the DEFINITIONS in a column to the right of the terms. You don't need to put any METATEXT between the glossary heading and the first term.
Often, a single term has more than one sense (more than one distinct concept that the term can mean). In this case, number the senses and define them in separate paragraphs, like this:
|
The above example shows two other techniques helpful in writing a glossary. First, a glossary is a good place for adding a little bit of supplementary information in addition to the pure definition. Don't try to say everything you know about the concept, but it helps to hint at why the concept is important, add extra introductory information such as typical sizes or typical values, and clarify any likely misunderstandings. A glossary is also a good place to explain graphical symbols for the concepts being defined.
Second, if you use a term in a definition that is defined elsewhere in the glossary, write the term in small capitals the first time it appears in the definition.
When defining an ACRONYM, it is seldom enough to say what each letter stands for. You must also define the concept that the acronym as a whole denotes:
|
Often, during a project you change terminology several times, or you find it necessary to revise your definitions of problem-domain terminology. Be sure to make all the terminology in the document consistent before you release it. It helps a lot if you update the glossary every day as you talk with the customer and write the document.
On a large project with many different requirements documents, you might want to make one big glossary for all the documents. This saves a lot of cutting, pasting, and inconsistency. This cumulative glossary can be quite a useful repository of knowledge for future projects. Another strategy is to collect all the new terms from each project and add them to a company-wide glossary. People can cut and paste from the company glossary on new projects. The company glossary can even help introduce new employees to their jobs.
Two Latin abbreviations, often confused. Their meanings:
|
i.e. |
that is | |
|
e.g. |
for example |
If you can't keep them straight, your readers probably can't, either. Just write "that is" or "for example" and you can't go wrong.
A statement disallowing "invalid data" can be appropriate in an overview or preliminary sketch, but not in a requirement, unless "invalid data" is precisely defined. It should not be up to the programmers to invent their own criteria of what sort of data is valid or invalid. Their job is to implement the actions described in the requirements or specification: if the input data is in such-and-such format, store it; if it's in such-and-such format, display such-and-such error message; if it's in yet another format, display yet another error message. When describing the desired output of the program at this level of detail, there is no need for the concepts valid and invalid, except to help a reader understand why it's useful for the computer to take this or that action.
Metatext is text that describes text in the document rather than the document's subject matter. For example, "The following paragraph describes..." or "This chapter describes..." Some metatext is unavoidable, such as a description of typographical CONVENTIONS , or a documentation guide to describe a set of documents or the contents of a large document. However, most metatext is nothing but clutter. It distracts from the ordinary text and therefore from the content; deleting metatext almost always improves a document.
A common place to put metatext is right after a section heading. The concern is that if you don't explain what's going to come in the section, a reader won't be able to understand it. For example:
| 3. Email This section describes email. 4. Format of Email Messages
4.1 Address Part The address part consists of four name/domain pairs . . . |
Much better than merely repeating a section heading in a sentence (a practice that is somewhat condescending to the reader) is to start by presenting some content that itself introduces the rest of the section. The most likely candidate for introductory content is a DEFINITION. Another good way to introduce content is to sketch it out, similar to an overview.
With introductory content in place of metatext, the above example could read like this:
| 3. Email Email is electronic mail: documents sent electronically from one user at one computer to one or more other users, possibly at different computers. 4. Format of Email Messages
4.1 Address Part |
If you find yourself writing metatext, try deleting it and seeing if the text is hard to follow. If it's easier to follow, as it usually is when interruptions are removed, then leave the metatext out. If it's harder to follow, then either put the metatext back--sometimes it is indeed necessary--or consider adding content that you may have skipped, like definitions, or rearranging the content so that each piece of information helps introduce the next, as described in section 14.3.
Good metatext is usually very short. Here's a very quick way to distinguish some examples from other text:
| An address has the format login@domain, where login is the user's
login name and domain is the name of the computer that exchanges mail for
that user.
Examples: george.gibbons@paydirt.com, v3873092@bryant.edu. |
This same quick technique also makes a nice introduction to digressions about rationale or special implications that you want the reader to understand. The word Rationale or Implication followed by a colon is the bare minimum of metatext you need and, therefore, the right amount.
Your motto as a technical writer should be "content right now," not "content next paragraph."
One of the most overworked words in the computer field. Save this word to mean an object that has been made to bear a useful analogy to something else, so that the model can be observed to learn something about what it is a model of. Model-building is a fundamental technique in software: the data stored in a computer is a model of the part of the world that the data represents. Often, users read the data to learn about some part of the world, hoping that the analogy between the data and the real world holds for the information they're trying to learn. Models themselves are neither true nor false, though the inferences that we base on them are.
Don't write model to mean concept, abstraction, conceptual framework, specification, process, description, diagram, or anything other than the plain sense of the word model. It's too confusing, especially to customers unfamiliar with the strange linguistic habits of the software community.
Here are a few simple subtitutions to illustrate how to fix phrases that contain these non-model senses of the word model:
| Confusing | Clearer |
|---|---|
|
| |
|
waterfall model |
waterfall process |
|
requirements model |
requirements |
|
use case model |
use cases |
The following is a recommended page layout for a requirements document or
specification. 
You can adjust this layout slightly--for example, you might move the outer margins around if you're making a double-sided document--but there are a few important aspects of it that you should retain.
The goal of a good page layout is to place everything harmoniously on the page so that it's easy to read, the reader's attention is directed to what they need to find, and the reader is never distracted by the page layout itself. This is a very easy goal to achieve, but some word processors' defaults create a cluttered layout that's difficult to read. Especially in a document that presents complex material that a reader must consider very carefully, you do not want the physical appearance of the page to make the material seem harder to understand than it really is.
Typical defaults in a word processor set the font to 10-point Times Roman with a line spacing of 11 points, and a text margin that is only 1/2" in from the left margin. The result is quite difficult to read, not just because the type is small, but because there are too many characters per line. Optimal readability is at about 40-70 characters per line; the defaults make lines with around 100 characters per line. By increasing the font size and making the left indent on normal text a whole inch, the number of characters per line is reduced to about 80. That's still above optimum, so you need another trick to improve readability: increase the line spacing. [3] With a line spacing of 14 points, even 11-point Times Roman at 80 characters per line looks quite spacious and readable.
This might seem complicated, but fortunately you only need to set it up in your word processor once; then you can forget about it.
The other important consideration in the recommended page layout is to frame the page. An 8-1/2"x11" page is so large that it loses its visual unity if text and graphics don't line up with the margins. Adding horizontal lines to the header and footer also helps the reader perceive the page as a cohesive whole. The left edge of screen shots should line up with the left margin or text margin, instead of being centered. Only very small graphics should be centered.
Paragraphs should be in block style: with one line of space between them, and not indented. This helps requirement, preference, and invariant statements fit harmoniously onto the page, in their highly emphasized format.
A word to avoid in most circumstances, due to its vagueness.
Philosopher Thomas Kuhn started the contemporary usage of the word paradigm in the book The Structure of Scientific Revolutions, where it was part of his theory that normal science is puzzle-solving with a well defined puzzle type--which he called a paradigm (remarkably similar to a problem frame). [4] Scientific revolutions, in his theory, are periods when scientists abandon one puzzle type for another.
Since then, the term has entered popular usage and changed somewhat. With Kuhn's original idea now faded and forgotten, paradigm serves mostly as a conveniently vague word to resort to when you don't want to go to the effort of clearly identifying what you want to say and then saying it--or, worse, where you want to impress someone with fancy language. Here are a few examples of how to improve sentences that contain the word paradigm:
|
Vague |
Clearer |
|---|---|
|
The DEX and VERBIS systems operate on different paradigms. |
There is no one-to-one mapping between the data elements stored in DEX and VERBIS. |
|
VERBIS represents a new paradigm in printed-circuit assembly. |
Better to say nothing at all, or else write: The following features in VERBIS have never before been implemented in software for automation of printed-circuit assembly: followed by a list of specifically what differentiates VERBIS from its competitors--though a survey of the market and the competition does not normally belong in a requirements document. |
|
The alarm-response process conforms to a three-step paradigm. |
When an alarm appears on the main monitor screen, the security staff carries out the following three steps: or When the system receives an alarm signal, it checks the following three conditions to ensure that it's not a false alarm: |
|
Accommodating the data warehouse will require a shift to a new paradigm. |
The types of read requests initiated by the data warehouse software differ from the read requests that our software fulfills, in the following ways: or We will need to redesign our record-locking scheme from scratch in order to accommodate the data warehouse. |
Here are some words that can replace paradigm, depending on your meaning: system, method, framework, scheme, description, technique, structure, set, set of predicates. Don't just replace paradigm with model , unless, of course, you're really talking about a model.
Representation is the relation between computer data and the real world. When we devise a convention for setting computer data to one of a set of states to indicate that something in the real world is in one of a corresponding set of states, we are making the data represent the real world.
Thus representation is one of the basic concepts of computers. Other sorts of representation implement the same principle: a sales representative informs potential customers of the offerings of the company that he represents. Both the human representative and the computer data "re-present" something that exists somewhere else and can't present itself directly.
Unfortunately, all too often people write the big word represents as a synonym for the little word is. For example:
Compliance with the new tax laws represents the most important goal of the new accounting system.
No, compliance with the new tax laws does not represent anything. It's not stored information or an indirect way of communicating. Sentences like that are usually the result of trying to make things more complicated than they really are. Better to just write:
Compliance with the new tax laws is the most important goal of the new accounting system.
Write the word represents only when you really mean it.
There are three main ways to word a requirement statement: in the present tense, with a modal verb like must or shall, and in the imperative mood (as a command).
| In the present tense: | |
| R-1 | A user can view landbase files in AutoCAD format. |
| R-2 | A user can run any of the following queries on demand: |
| R-3 | When the passcode is entered at the gate, the gate toggles between locked and unlocked. |
| R-4 | WATCHCOM notifies the user when the gas pressure on any pressurized cable falls below its allowable minimum. |
| With a modal verb: | |
| R-1 | A user must be able to view landbase files in AutoCAD format. |
| R-2 | A user shall be able to run any of the following queries on demand: |
| or | |
| R-2 | VSYS shall answer any of the following queries on demand: |
| R-3 | When the passcode is entered at the gate, the gate must toggle between locked and unlocked. |
| R-4 | WATCHCOM shall notify the user when the gas pressure on any pressurized cable falls below its allowable minimum. |
| In the imperative mood: | |
| R-1 | View landbase files in AutoCAD format. |
| R-2 | Answer any of the following queries on demand: |
| R-3 | When the passcode is entered at the gate, toggle the gate between locked and unlocked. |
| R-4 | Notify the user when the gas pressure on any pressurized cable falls below its allowable minimum. |
It's hard to go wrong with the present-tense format. It easily accommodates mentioning both the user and the system, if necessary, and it is especially well suited to describing required problem-domain activity without mentioning the system, as in R-2 above.
Writing requirements with a modal verb almost always creates longer, more obscure sentences, and is therefore not recommended. For example, where the present tense allows you to say "a user can," the modal-verb format requires "a user shall be able to." Unfortunately, some organizations, including the United States government, require use of the word shall in requirements as part of the terms of the contract. In this case, you have no choice; but if you have a choice, you should pick one of the other two formats. Also, if you write requirements with a modal verb, be sure to make it consistently must or consistently shall throughout the document. The modal verb should is best reserved for preferences, not requirements, as it does not connote the kind of finality that you want in a requirement statement.
The imperative mood creates the simplest requirement statements. However, as in R-1 and R-2 above, sometimes it omits too much. If the user is supposed to activate some capability of the software, such as a query, it's best to mention the user explicitly, as the present tense allows. The imperative mood works best for requirements involving notifying a user: there the sentence can mention the user as the object of the verb. You can mix requirement statements in the present tense and indicative mood in the same document, reserving the indicative mood for notification and the present tense for all other types of requirements. [5]
It's usually best to avoid the future tense in requirement statements. The future tense is best reserved for describing development activity to occur after the document is complete, like "Future versions will add support for more landbase formats, as needed."
Often, a requirement contains a lot of small details: various different activities that are supposed to occur depending on several different conditions. Rather than write an enormously complex sentence, or a series of many nearly identical sentences, make the requirement refer to a TABLE describing the rule. The table from the tax instructions in section 11.5, along with the accompanying "many sentences" version, gives a good illustration of how much more readable the table is. You can word the requirement statement that precedes the table like this:
| R-5 | Send delinquency notices to customers as described in the following table: |
| or | |
| R-5 | Send delinquency notices to customers as described in table 1.1. |
Rules are abstract. Because requirements almost always describe rules, requirements are also abstract, and, consequently, they can be difficult to understand without some commentary. Typical helpful commentary is definitions, examples, and explanations of rationale. By putting requirements into bold sans serif type, as noted under CONVENTIONS , you can easily weave short comments into the requirements without creating confusion.
Here's an example. The figure 10 referred to below is a graphic illustrating each concept, omitted here for brevity. Page numbers that the example refers to are indicated by XX.
| |||||||||||||||
Notice that the principles of grouping and sequence discussed in chapter 14 are at work in this example. All the information grouped under R-6 has a simple and obvious common denominator: landbase features that a viewer can view. All of this information is collected together in one place, not scattered throughout the document. However, the description is not allowed to stray from its purpose. The reader is referred elsewhere for more details about centerlines and network design; these are covered in depth in other sections. The principles of sequence are at work in the decision to describe centerlines after right-of-ways: the definition of centerline refers to right-of-ways in its differentia and, therefore, requires the reader to first understand what a right-of-way is.
In addition to showing how to intersperse commentary with requirements, this example also demonstrates a simplifying technique that is almost indispensible in any requirements document: writing many endings to a single sentence. If you need to write several requirements about the same thing, write the common part as the beginning of a sentence, and write the different parts as " sentence-completions."
The following is mind-numbing:
|
|||||||||||||
The following says the same thing, but is much simpler and easier to understand:
| ||||||||||||
The en dashes help to visually relate the sentence-completions to the sentence-beginning at the top. They're especially valuable if you intersperse commentary with the requirements, as in the example of R-6, above.
Usually you can combine create, read, update, and delete into a single requirement statement. People think of them as four aspects of a single capability: full access to a database. While, technically, they are four separate capabilities and will require at least four separate test cases, writing them as four separate statements usually makes the information seem four times as complex as it really is.
Almost any group of very similar statements is best communicated with a table. If you find yourself writing a very long series of sentences that have the same structure, a table is likely to be both clearer and easier to make.
| Confusing | Clearer | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
| |||||||||||||||||||||
| The Address group contains street addresses and is stored on layer 20. The Drops group contains drop cables and is stored on layers 11, 12, 50, 65, 66, 102, 104, and 119. The Land group contains all landbase features and is stored on layers 1 through 50. The Quartz group contains Quartz output and is stored on layers 123 through 244 and 251 through 255. The PoleNo group contains attribute text of utility poles and is stored on layer 70. |
| ||||||||||||||||||||
| Confusing | Clearer | |
|---|---|---|
|
| ||
| A bug must be assigned to both a programmer and a tester unless its status is Code or NFBC, in which case it need not be assigned to either, except that a bug in Fixed status must be assigned to a programmer but doesn't have to be assigned to a tester. |  | |
Notice how few horizontal and vertical lines a table needs. Many tables need no lines at all. The fewer lines you can draw on a table while still grouping all information that needs to be grouped, the less clutter you add and the more you emphasize the contents of the table.
You can reduce the apparent complexity of the document by putting information on the title page that would otherwise go into separate numbered sections, each introduced by METATEXT.
If the table of contents can fit on the title page, then it belongs on the title page. There it provides a quick overview of the document, inviting people inside if the headings appear relevant to their work.
Information to include on the title page:
An eye accustomed to reading English normally scans a page from upper left to lower right. Since the company logo is merely a nicety rather than information specific to the project, put it in the upper right or lower left, out of the eye's customary path. Whatever you do, don't center it.
Under "Prepared by," note that these aren't movie credits, so you need only mention the people who actually wrote the document. There should only be one or a few such people. You don't need to mention every manager, programmer, tester, or customer representative who reviewed the document, nor the company that catered the meetings.
Mention names of people, not merely a company. A phrase like "Prepared by: Splenetix Corporation" hides the people involved, suggesting that no one wants to take responsibility for the contents or to be contacted if there is a problem. Including your name says, "I did this, and I stand by it."
Everything seems to have a "type" or "type code" of some sort. That's what makes the word type so vague. But there's an easy solution: coin a phrase (there's no need for an ACRONYM) that explicitly states the type of the type. Inside a gravel class, you might have a type attribute to indicate whether it's lawn gravel, parking-lot gravel, and so forth. Name this attribute gravel type, even though it's in the gravel class. That way, elsewhere in the same application, you won't be confused by the type codes in the truck, scale, mine, and pulverizer classes. Those attributes, of course, you should name truck type, scale type, mine type, and pulverizer type.
Naturally, before being satisfied with such a generic strategy, first try to find substitute words at a lower level of abstraction. pulverizer type might be better named pulverizer method or pulverizer size--or you might need both attributes.
Don't underline. Underlining is a substitute for italics, invented for typewriters and handwriting. When applied to a proportional font such as Times Roman or Arial, it adds clutter more than emphasis.
The exception is monospace fonts like Courier, which have no italics or bold face. (Most software can create an italic or bold version of them, but only by mechanically slanting or darkening the letters, resulting in an ugly and unreadable distortion.) Underlining is meant for monospace fonts, and only for monospace fonts.
Every time you write the word use, think a second time. Usually you can replace it with a more specific verb, though not always. Use is an extraordinarily vague word: it means any sort of process involving an object to yield a result. If the reader does not already know this process, they won't understand. The writer, however, is often baffled by this lack of comprehension because when the writer sees the word use in the same context, he unconsciously fills in the details of the process. When you write it, you might be thinking, "the system reads the barometric pressure from the sensor and plugs it into the forecast formula," but a reader won't understand that if all they see is, "the system uses the sensor to make forecasts."
Some alternatives: a user runs a program; the system reads or stores data; a variable or state indicates some condition (instead of "the system uses this variable to check some condition"); a program or function calls a function or service. Spell out the meaning as concretely as possible.
The phrase is used to is especially confusing. Very often, you're trying to say what something is, but is used to describes what people do with the thing rather than the thing itself. If you say that a function in an API "is used to" calculate some value, you're writing vaguely about why a programmer might write code to call that function, but you haven't said what the function does. If the function is used to calculate some value, does that mean that it returns that value or that it performs some intermediate calculation that "is used to" calculate the final result in combination with other processing? Just say what value the function returns or what effects it has. It is often useful to explain why a function in an API is useful to a calling program; but do so in a separate sentence or paragraph, after you've explained what the function does.
| Vague or wordy | Clearer |
|---|---|
|
| |
| The Permissions window is used to set up the authorization database. | In the Permissions window, the system administrator sets up the authorization database. |
| Test 16A is used to test the report generator. | Test 16A tests the report generator. |
| The Monitor window is used to choose which track to disable. | In the Monitor window, a user disables a track by selecting it and clicking the disable button. |
Notice how much clearer sentences become when you mention the user explicitly.
See INVALID.
A verb is said to be in the active voice if its subject is the agent of the action denoted by the verb, or in the passive voice if its subject is the object of the action. For example, the verb in "VSYS prints month-end reports" is active; the verb in "Month-end reports are printed by VSYS" is passive.
The active voice emphasizes the agent of the action; the passive voice emphasizes the object. Emphasizing the object entails de-emphasizing the agent. This is especially so when a sentence with a passive verb omits the agent entirely, as in "Month-end reports are printed."
While both forms of emphasis have their uses, the passive voice is often a terrible temptation. You should use it only consciously and deliberately to achieve an unusual form of emphasis, not as your habitual way of framing a sentence. The temptation comes from the fact that when you're writing, especially about something in computers, what's on your mind is how some object is affected by an action, not the agent of the action, and often it's hard to identify any distinct agent. However, for a reader to understand the action you're talking about, often you must make the agent explicit.
The following are a few examples of how to convert passive sentences to active:
| Vague passive | Explicit active |
|---|---|
| When the Scheduled Reports window is closed, the month-end report is printed. | When the user closes the Scheduled Reports window, VSYS prints the month-end report. |
| Obsolete bar codes prevent products from being identified. | The system cannot identify a product if it has an obsolete bar
code.
or An auditor cannot identify a product if it has an obsolete bar code. |
| MDU data is exported only once to VSYS. | Once a caller has exported MDU data to VSYS, it can never export
it again.
or VSYS requests MDU data from a caller only once per session. |
Sometimes a sentence has every verb in the active voice but still has the vagueness or woodenness usually associated with the passive:
| Active in form, passive in spirit | Explicit and direct |
|---|---|
| Failure to include an authorization record will result in rejection of the file by VSYS. | If the caller does not include an authorization record in the file, VSYS rejects the entire file. |
If your word processor has a grammar checker, it probably tries to tell you what proportion of verbs in a document are passive, or perhaps flags every passive verb with the recommendation that you change it to active. However, many verbs that have the appearance of being passive actually refer to states and not to actions. For example, most grammar checkers would flag is loaded as passive in the sentence "If a tape is loaded, the tape drive begins reading it." However, loaded in this context is actually an adjective referring to the state of the tape: loaded or not loaded. States don't have agents, so there is no way to reword the sentence to make the verb active, at least not without talking about something else; the if part of the sentence is not about an action.
1. See section 13.4.
2. This is G. Polya's "problem to find," which he wrote about in How to Solve It.
3. Dynamics in Document Design, by Karen Schriver, pp. 260-263, presents some of the research on line spacing, line length, and readability.
4. The older meaning of paradigm was an example that illustrated a pattern in its most ordinary or archetypal form. An example is amo, amas, amat, amamus, amatis, amant, illustrating the pattern of inflections of one of the major types of verbs in Latin, by showing how just one verb, amare, meaning "love," is inflected. Memorize the paradigm and you can inflect another verb that follows the same pattern: secare, meaning "cut," goes seco, secas, secat, secamus, secatis, secant. This sense of the word paradigm is very useful, and not unduly vague. Unfortunately, most people are not familiar with it, and that's a reason to avoid it in most circumstances--in addition to its having been supplanted by the vague variations on Kuhn's sense of the word.
5. Technically, mood and tense are two independent variables of a verb. The first group of requirement statements shown above is in the indicative mood and the present tense, and the third group is in the imperative mood and the present tense. For most purposes, though, it's enough to call them "present tense" requirements and "imperative mood" or "command" requirements.
