How To Write Maintainable Engineering Specifications. Forrest Warthman

Transcription

1 1

2 How To Write Maintainable Engineering Specifications Forrest Warthman 2

3 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 3

4 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. 4

5 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. 5

6 Editing Tools Writing tools: Microsoft Word (versions 2003, 2004, 2007): Price range: $150 to $300. Pros: learning time. Cons: control problems. Adobe FrameMaker (versions 6, 7, 8, 9): Price range: $800 to $1,500. Pros: fast, very reliable control. Cons: price. Vector-graphics tools: Microsoft Visio (versions 2002, 2003, 2007): Price range: $100 to $450. Pros: learning time. Cons: control, productivity. Adobe Illustrator (versions 10, 11, CS2, CS3, CS4): Price range: $150 to $500. Pros: productivity. Cons: learning time. 6

7 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. 7

8 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. 8

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

10 Formats Microsoft Word 2007: 1. Home > Styles 2. Select text and apply formats

11 Formats FrameMaker: 1. Click icons in upper-right corner of document window to open character and paragraph catalogs. 2. Select text and apply formats

12 Document Templates Microsoft Word 2003 or 2004: 1. Tools > Templates and Add-Ins Check Automatically update document styles, and click Attach Select template document, and click Open. Word templates define page layouts, paragraph and character formats, and other things

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

14 Document Templates FrameMaker: 1. View > Master Pages 2. View > Reference Pages

15 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. 15

16 Global Variables You can define variables for an entire document: variable name = value Example: product_name = H-5035 GPU Insert references to the variable name: Any number of references, anywhere in the document. Example: The product_name is a 3 GHz graphics processor. Appears as: The H-5035 GPU is a 3 GHz graphics processor. Change a variable s definition at any time: Changed definition: product_name = N-6095 GPU Appears as: The N-6095 GPU is a 3 GHz graphics processor. 16

17 Global Variables Microsoft Word 2003 or 2004: 1. To create a variable, Insert > AutoText > AutoText 2. Type the variable name, and click Add. 3. To insert the variable, place cursor at point of insertion, and click Insert

18 Global Variables Microsoft Word 2007: 1. To create a variable, type variable name in document text and select the text, then Insert > Quick Parts > Save Selection to Quick Part Gallery 2. In Create New Building Blocks window, click OK to save name. 3. To insert the variable, place cursor at point of insertion, then Insert > Quick Parts > Building Blocks Organizer. 4. Select variable in Building Blocks Organizer window, and click Insert

19 Global Variables FrameMaker: 1. To create a variable, place cursor at point of insertion, then Special > Variable Click Create Variable in the Variables window. 3. Type the variable name and definition, and click Add and Done. 4. To insert the variable at the cursor s position, click Special > Variable..., select the variable, and click Insert

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

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

22 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) Result 22

23 Inserting Figure Captions Microsoft Word 2007: 1. Insert a carriage return where the figure caption (title) will go. 2. References > Insert Caption. 3. Enter the caption, and click OK Result 23

24 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 Select anchoring position (Below Current Line), and click New Frame Result 24

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

26 Inserting Figure Captions FrameMaker: 1. Place cursor where the figure caption (title) will go, and apply the appropriate paragraph format. 2. Enter the caption

27 Inserting Tables Microsoft Word 2003 or 2004: 1. Insert a carriage return where the table will go, and move cursor to the beginning of the following line. 2. Table > Insert > Table 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 Enter the table caption (title), and click OK Result 27

28 Inserting Tables Microsoft Word 2007: 1. Insert a carriage return where the table will go, and move cursor down to the beginning of the following line. 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 Result 28

29 Inserting Tables FrameMaker: 1. Move cursor to the end of the paragraph above which the table will be placed. 2. Table > Insert Table Specify the table parameters, and click Insert. 4. Drag cursor across all table cells to select them

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

31 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. 31

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

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

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

35 Comparing Documents Microsoft Word 2003 or 2004: 1. Tools > Compare and Merge Documents 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 Result 35

36 Comparing Documents Microsoft Word 2007: 1. Review > Compare > Compare Browse for original and revised documents, and click OK. Save the new document with a unique filename Result 36

37 Comparing Documents FrameMaker: 1. From the first document (called the Newest Document), File > Utilities > Compare Documents Browse for the second document (called the Oldest Document), and click Compare Result 37

38 Language Use clear, simple language: Every sentence needs a subject (noun phrase) and a predicate (verb phrase). Right: Software must set the Stop bit at boot time. Wrong: The Stop bit is set at boot time. This does not say what performs the action software or hardware. Use the present tense, active voice: Fast to read: Input A sets the Stop bit Slower to read: The Stop bit will be set by input A. We prefer specifications that can be read fast. That means fewer words and characters. For most readers, English is a second language. They appreciate simplicity and clarity. 38

39 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? 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. 39

40 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 a good name: function, engine, or block. Choose only one name, and stick with it. 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. 40

41 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). 41

42 References Use clear references: What are this and that referring to? Here is an 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? (a) writing programs that make far calls, (b) running under an operating system that stores far calls in distant disk tracks, or (c) using a hard disk? 42

43 The Bottom Line Make your documents: Easy and fast to read. Easy and fast to maintain. Easy and fast to adapt for multiple uses. 43

44 44