Specifications

…writing descriptive detail

Specifications: Purpose

Document a product in enough detail that someone else could create or maintain it.

Note: “Specifications” is always plural.

Specifications: Audience

• The person who is going to build or maintain it

• The user is not the audience

• There is no “you” in Specifications

• Tone = formal

Specifications: Scope • Require exhaustive detail

– Means you leave nothing unspecified

– Everything that is implicit is made explicit

– Nothing is left to the imagination – nothing is assumed

• Need to provide both textual descriptions and illustrations– Illustrations supplement descriptions – do not replace them

• Usually adhere to a hierarchical outline format– Mirrors the organization of most programs: hierarchical

– Use menu “trees” that break down into commands or trees of their own

• Are usually lengthy documents

Keys to Writing Specifications

• Translate acuity to effective, accurate descriptions– Expand with details, examples, comparisons, analogies

– Use illustrations

– Label items you refer to (use callouts in illustrations)

• Use a hierarchical approach

• Focus on what it is, not what it is not

• Avoid circular definitions

• Find that the devil is in the details

Explanatory Methods• Extended definition

– Need more than one phrase or sentence to explain– Explore a number of qualities– Usually give example to help reader

• Definition by analogy– Helps to show similarities with familiar

• Definition by cause– Explain cause

• Definition by components– Break concept into its component parts

• Definition by exploration of origin• Negative definition

– Effective only when the reader is familiar with what is being contrasted

Specifications: Organization1. Introduction

• Where you include the overall purpose

2. Requirements• Where you identify what is required to build it

(e.g., materials)

3. Description• Where you describe it (not what it does)• Include all specific details (e.g., measurements, color, shape)

4. Functionality• Where you describe the function of each part mentioned in 3• Refer to your callouts and figures in your text

Note: Parts 3 and 4 have the exact same hierarchy.

Two Common Outlining SchemesNumbering SchemeI.

A.1. a. 1)

i) b.2.

B.II.

A.1.

Decimal Numbering Scheme

1.

1.1

1.1.1

1.1.2

1.1.2.1

1.2

1.2.1

2.

2.1

2.1.1

Things to remember…• Alignment

– Review Williams on the “Definite Line” rule. Because this paper is using outlines and hierarchies, be sure that every indentation means something hierarchically. (See outline scheme.)

• Proximity– Be sure to provide more space between separate sections than you

allow between lines within those sections.

• Systemic Progression– Carefully consider the order that you will cover the appearance.

Remember that English people view top to bottom, left to right.

• Description, not Functionality– Remember not to stray into the functionality when you’re

describing the product. Save that for the functionality section.

More things to remember…• Hierarchy

– Be sure your document adheres to a consistent system of hierarchy.– Do not go down in your hierarchy for descriptions, only for

sub-parts.

• Overview– Remember to provide an overview statement. – Paragraph form, not outline format

• Setup– Cut excess repetitive words or phrases by mentioning commonality

in a set-up statement in the overview.– Reserve the itemized description for the distinguishing

characteristics.

• POV– Remember not to address the user as “you.”

Even more things to remember…

• Parallelism– Be sure all lists are parallel, whether each item begins with an

infinitive verb (to do something), an imperative verb (do something!), a gerund (doing something), a noun (something), or any other form.

• Graphics– Label all graphics.

– Graphics do not replace text descriptions; they enhance them.

• Everything– Do not omit descriptions on the basis of “common knowledge.”

Specifications specify everything.

Even more details to remember…

• Headings– Never follow a heading with a pronoun that assumes a reference to

that heading. A heading is a title, not part of the text that follows it.

E.g., if your heading was “Rod,” you would not follow it with …This is a ….

• Do not itemize or list qualities, like a dictionary definition– You would not say:

1. Flight icon; (a) it is square; (b) it contains and image of a bird; (c): the bird is blue.

– You would say:

1. Flight icon: a square containing an image of a blue bird.

Even more things to remember…

• Numbers– Write out numbers lower than ten. See Harris for other rules.

• Order of modifiers– When stringing a long list of modifiers in front of a noun, English

requires they be in a specific order:

number size shape age color NOUN

Ten 5/8th-inch long, cylindrical blue screws

Note: the comma in that list of modifiers…

Even more things to remember…

• Apply the proper rules for hyphenating modifiers– Hyphenate measurements as a compound adjective when it occurs

before a noun.

An eight-inch rod

– Do not hyphenate when it is the object of a preposition following a noun

The rod of eight inches in length

– Do not hyphenate if the measurement occurs in the predicate

The rod is eight inches long

• Use present tense

Be DescriptiveRevise/rewrite for correctness and descriptiveness.

1. There is a 5-inch rod by 8-inches extending from the handle.

2. The Title bar is a blue stripe that is at the top of the window and that is the width of the screen.

3. The New Document is a white rectangle with a small downward pointing triangle that is where the corner usually is.

4. There is a list of tasks that will be presented in the Task Box.

5. There is a change in the color of this indicator button when there is a message that is incoming.