How To Write Maintainable Engineering Specifications

1 How To Write MaintainableEngineering Specifications 1 Forrest WarthmanOutline 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 references2 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 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?

2 What do theyneed to know? Imagine yourself as the audience. Start by writing an unordered list of topics to cover, then add some order to the 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. 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.

3 Other tools: PowerPoint is nota 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 > Styles and text and apply Microsoft Word 2007 > text and apply icons in upper-right corner of document window to open character and paragraph text and apply Templates Microsoft Word 2003 or 2004 > Templates and Automatically update document styles,and click template document,and click templates define page layouts, paragraph and character formats, and other Templates Microsoft Word 2007 Button > Word > Manage > Templates > Automatically update document styles, and click template document,and click Templates > Master > Reference Conventions: Do not use multiple tab charactersto position text.

4 Instead, use a predefined paragraph format. Do not use multiple carriage returnsto 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 Arialor Verdanafonts, sizes 10, 11, or 12. Documents with many fonts or font sizes look Figures Microsoft Word 2003 or 2004 a carriage return where the figure will > Picture > From picture file, and click Link to File(reduces file size). Figure Captions Microsoft Word 2003 or 2004 a carriage return where the figure caption (title) will go. > Reference > the caption, and click Figures Microsoft Word 2007 a carriage return where the figure will go. > Picture. picture file, and click Link to File(reduces file size). Figure Captions Microsoft Word 2007 a carriage return where the figure caption will go. > Insert Caption. the caption, and click Figures on View > Borders(lets you see where the figure will go).

5 A carriage return where the figure will go. > Anchored anchoring position (Below Current Line), and click New Figures(continued) the anchored > Import > file, check Import By Reference,and click image resolution (try the Custom value),and click Figure Captions cursor where the figure caption will go, and apply the appropriate paragraph format. the Tables Microsoft Word 2003 or 2004 a carriage return where the table will > Insert > number of rows and columns, select Fixed column width: Autofor Autofit behavior, and click cursor above table, and Insert > Reference > the table caption (title), and click Tables Microsoft Word 2007 a carriage return where the table will > Table, and drag cursor to select number of rows and cursor to the line above the table, and References > Captions > Insert the table caption (title), and click Tables cursor to the end of the paragraph below which the table will > Insert the table parameters, and click cursor across all table cells to select Tables(continued) > Resize By Scaling to Widths Totaling, and click the table title (caption).

6 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 Footnotes Microsoft Word 2003 or 2004 cursor at point of footnote insertion. > References > the footnote Footnotes Microsoft Word 2007 cursor at point of footnote insertion. > Insert the footnote Footnotes cursor at point of footnote insertion. > the footnote Documents Microsoft Word 2003 or 2004 > Compare and Merge file to be compared, and click Merge into new the new document with a unique not use Track Changes with large or complex Documents Microsoft Word 2007 > Compare > for original and revised documents, and click the new document with a unique filename.

7 Documents the first document (called the Newest Document), File > Utilities > Compare for the second document (called the Oldest Document), and click 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 whatperforms 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 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.

8 " 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 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?

9 Using a system that stores far calls in distant disk tracks? Using a hard disk?37 The Bottom LineMake your documents Easy and fast to read. Easy and fast to maintain. Easy and fast to adapt for other uses. 38