How To Write MaintainableEngineering Specifications

1

Forrest Warthman

Outline

• Motivations and audience• Editing and vector-graphics tools• Document formats and templates• Inserting figures and tables• Inserting footnotes• Comparing documents• Use of language, words, names, and references

2

Motivations

• Engineering specifications serve several functions:– Clarify agreements on design goals.– Guide for new members of engineering team.– Starting point for other documents

(patent applications, user guides, marketing collateral).

• For each function:– Audience is different.– Content needs to be modified or expanded.– Ease of modification depends on how well the original

specification is written and formatted.

3

Audience

• It is more diverse than your immediate team:– Others don’t know details of product functions.– Others don't know all the names and acronyms.– Others have different questions than you do.– Others may have different language skills.

• Before you start writing, ask:– Who are your audiences?– What do they need to know?– Imagine yourself as the audience.– Start by writing an unordered list of topics to cover,

then add some order to the list.

4

Editing Tools

• Writing tools:– Microsoft® Word (versions 2003, 2004, 2007):

• Price range: $150 to $300.• Pros: learning, price. Cons: control, productivity.

– Adobe® FrameMaker® (versions 6, 7, 8, 9):• Price range: $800 to $1,500.• Pros: control, productivity. Cons: learning, price.

• Vector-graphics tools:– Microsoft Visio® (versions 2002, 2003, 2007):

• Price range: $100 to $450.• Pros: learning. Cons: control, productivity.

– Adobe Illustrator® (versions 10, 11, CS2, CS3, CS4):• Price range: $150 to $500.• Pros: control, productivity. Cons: learning.

5

Editing Tools

• Built-in drawing tools:– Avoid using built-in Word or FrameMaker draw tools.

• Hard to control.• Can’t be imported into other software tools.

• Tool versions:– Have all contributors use the same tool and version.

• Formatting problems with cross-version Microsoft® Word.• Especially important for external collaboration.

• Other tools:– PowerPoint® is not a document-editing tool.

• No named formats, no cross-page text flow, poor draw tools.• Content requires reconstruction in Word or FrameMaker.

6

Formats

• Always use standard formats for characters, paragraphs, page layouts, tables, and figures:– Learn and use your company’s formats, if they exist.

• Does your company automatically update formats periodically?

• If so, tell your IT department about external collaborators.

– Otherwise, learn and use built-in formats in Word or FrameMaker.

– Do not modify fonts or spacing of individual characters or paragraphs.

• Instead, apply a standard format.

7

Formats

• Microsoft Word 2003 or 2004:1. Format > Styles and Formatting...2. Select text and apply formats.

1. 2.

8

Formats

• Microsoft Word 2007:1. Home > Styles2. Select text and apply formats.

1. 2.

9

Formats

• FrameMaker:1. Click icons in upper-right corner of document window to open

character and paragraph catalogs.2. Select text and apply formats.

1. 2.

10

Document Templates

• Microsoft Word 2003 or 2004:1. Tools > Templates and Add-Ins...2. Check Automatically update document styles, and click Attach...3. Select template document, and click Open.

Word templates define page layouts, paragraph and character formats, and other things.

1. 2. 3.

11

Document Templates

• Microsoft Word 2007:1. Office Button > Word Options...2. Add-Ins > Manage > Templates > Go3. Check Automatically update document styles, and click Attach.4. Select template document, and click Open.

2. 3. 4.

12

1.

Document Templates

• FrameMaker:1. View > Master Pages2. View > Reference Pages

1. 2.

13

Formats

• Conventions:– Do not use multiple tab characters to position text.

• Instead, use a predefined paragraph format.

– Do not use multiple carriage returns to position text.• Instead, use a predefined paragraph format.

– Do not modify the font of an individual character.• Instead, use a predefined character format.

– Use a small number of common fonts and font sizes.• For example, use Arial or Verdana fonts, sizes 10, 11, or 12.• Documents with many fonts or font sizes look chaotic.

14

Inserting Figures

• Microsoft Word 2003 or 2004:1. Insert a carriage return where the figure will go.2. Insert > Picture > From File... 3. Select picture file, and click Link to File (reduces file size).

1. 2. 3. Result

15

Inserting Figure Captions

• Microsoft Word 2003 or 2004:1. Insert a carriage return where the figure caption (title) will go. 2. Insert > Reference > Caption... 3. Enter the caption, and click OK.

1. 2. 3. Result

16

Inserting Figures

• Microsoft Word 2007:1. Insert a carriage return where the figure will go. 2. Insert > Picture. 3. Select picture file, and click Link to File (reduces file size).

1. 2. 3. Result

17

Inserting Figure Captions

• Microsoft Word 2007:1. Insert a carriage return where the figure caption will go. 2. References > Insert Caption. 3. Enter the caption, and click OK.

1. 2. 3. Result

18

Inserting Figures

• FrameMaker:1. Turn on View > Borders (lets you see where the figure will go). 2. Insert a carriage return where the figure will go. 3. Special > Anchored Frame...4. Select anchoring position (Below Current Line), and click New

Frame.

1. 2. 3. Result4.

19

Inserting Figures (continued)

• FrameMaker:5. Select the anchored frame.6. File > Import > File...7. Select file, check Import By Reference, and click Import.8. Select image resolution (try the Custom value), and click Set.

5. 6. 7. Result8.

20

Inserting Figure Captions

• FrameMaker:1. Place cursor where the figure caption will go, and apply the

appropriate paragraph format. 2. Enter the caption.

1. 2.

21

Inserting Tables

• Microsoft Word 2003 or 2004:1. Insert a carriage return where the table will go.2. Table > Insert > Table... 3. Set number of rows and columns, select Fixed column width:

Auto for Autofit behavior, and click OK.4. Move cursor above table, and Insert > Reference > Caption...5. Enter the table caption (title), and click OK.

1. 2. 3. Result

22

4. 5.

Inserting Tables

• Microsoft Word 2007:1. Insert a carriage return where the table will go.2. Insert > Table, and drag cursor to select number of rows and

columns.3. Move cursor to the line above the table, and References >

Captions > Insert Caption.4. Enter the table caption (title), and click OK.

1. 2. 3. Result

23

4.

Inserting Tables

• FrameMaker:1. Move cursor to the end of the paragraph below which the table

will go.2. Table > Insert Table... 3. Specify the table parameters, and click Insert.4. Drag cursor across all table cells to select them.

24

1. 2. 3. 4.

Inserting Tables (continued)

• FrameMaker:5. Table > Resize Columns...6. Choose By Scaling to Widths Totaling, and click Resize.7. Enter the table title (caption).

25

5. 6. 7.

Figures and Tables

• Conventions:– Do not copy figures or tables from other applications

and paste them into your Word or FrameMaker document.

• Instead, use the insert functions in Word or FrameMaker.• Pasted objects may cause incorrect flow of text that is added

or deleted.

– Use the standard method of inserting captions (titles).• Otherwise, figures and tables cannot be cross-referenced

correctly.

26

Inserting Footnotes

• Microsoft Word 2003 or 2004:1. Place cursor at point of footnote insertion. 2. Insert > References > Footnote...3. Click Insert.4. Type the footnote text.

1. 2.

27

3. 4.

Inserting Footnotes

• Microsoft Word 2007:1. Place cursor at point of footnote insertion. 2. References > Insert Footnote.3. Type the footnote text.

1. 2.

28

3.

Inserting Footnotes

• FrameMaker:1. Place cursor at point of footnote insertion. 2. Special > Footnote.3. Type the footnote text.

1. 2.

29

3.

Comparing Documents

• Microsoft Word 2003 or 2004:1. Tools > Compare and Merge Documents... 2. Select file to be compared, and click Merge into new document.

Save the new document with a unique filename.Do not use Track Changes with large or complex documents.

1. 2. Result

30

Comparing Documents

• Microsoft Word 2007:1. Review > Compare > Compare... 2. Browse for original and revised documents, and click OK.

Save the new document with a unique filename.

1. 2. Result

31

Comparing Documents

• FrameMaker:1. From the first document (called the Newest Document),

File > Utilities > Compare Documents... 2. Browse for the second document (called the Oldest Document),

and click Compare.

1. 2. Result

32

Language

• Use clear, simple language:– Every sentence needs a subject (noun phrase) and a

predicate (verb phrase).• Wrong: “The Stop bit is set at boot time”. This does not say

what performs the action—software or hardware.• Right: “Software must set the Stop bit at boot time”.

– Write sentences that can be read fast. • Fewer words and syllables.

– For most readers, English is a second language.• They appreciate simplicity and clarity.

33

Words

• Clear and unclear words and symbols:– What does “MSB” mean?

• Most-significant byte, or most-significant bit? • Does it specify not only memory ordering but also what

comes first-in-time on a serial link or a parallel bus?

– Does slash (/) mean AND or OR or both?• Some engineers are not always clear about this.

– Do not use undefined abbreviations or acronyms.– If you use abbreviations or acronyms, define them

where you use them, and provide a glossary at the beginning or end of the document.

34

Names

• Use names consistently:– Here is an example:

• "An AND gate can be built from a NAND, and a NAND would require two less gates than an AND."

• So, what does “gate” mean? Is it the AND or NAND, or is it a subcomponent from which the AND and NAND are made?

– Always use the same name for the same thing:• Pick one name for each thing: “function” or “block”.• Use only that name; do not use aliases (synonyms).• Undeclared aliases in computer programs result in errors.• Human brains work like computer programs in this respect.

– This is a BIG problem in engineering specifications.

35

Compounds

• Compound Nouns and Noun-Modifiers:– What does “ten tapped filters” mean?

• "ten filters with taps“?• "filters with ten taps“?

– Add a hyphen to clarify the meaning:• “ten tapped-filters” (hyphenate the compound noun).• “ten-tapped filters” (hyphenate the compound noun-modifier).

36

References

• Use clear references:– What are “this” and “that” referring to?– Example:

• “The disk drive makes a loud rattle when a programmatic branch causes the head to seek a distant track; this should be avoided.”

• So, what “this” should we avoid?– Writing programs that make far calls?– Using a system that stores far calls in distant disk tracks?– Using a hard disk?

37

The Bottom Line

Make your documents• Easy and fast to read.• Easy and fast to maintain.• Easy and fast to adapt for other uses.

38