CSc 190 - Senior Project Writing Software Documentation Some Guidelines http://gaia.ecs.csus.edu/~buckley/csc190/writingguide.pdf 1
Technical Documentation Known Problems Surveys say: Lack of audience definition Poor structure Disdain for the reader Unclear writing Poor use of illustrations 2
Technical Writing Be clear about what exactly is the purpose of the document you are writing. This means, who is going to read it and why. Use the Map Analogy Think of reader undertaking a journey the reading of your document. You are supplying a well annotated map for that reader. Remember the Technical Writer s Golden Rule Always put yourself in the reader s place. 3
Basic Solutions Understand your audience Address the reader directly Keep the information manageable Use illustrations wherever possible Don t just write, rewrite (it s a process!!) Give readers access to what they want Make sure the facts are accurate Allow for readability factors 4
Senior Project Style Manual All documents will have an Introduction as the first section. This serves as the executive summary for the document as such, it should be written last. 1 Introduction. 1.1 Purpose. 1.2 Scope. 1.3 Definitions, acronyms, abbreviations. 1.4 References. 1.5 Overview. Glossary 5
Numbering Sections and Subsections 1 1.1 1.1.1 1.1.2 1.1.2.1 1.1.2.2 1.1.2.2.1 1.1.2.2.2 Headings should clearly describe the contents of the section or subsection. Section Headings in UPPER CASE. Subsection Heading words capitalized. Section Headings and Subsection Titles in BOLD and ending with a period. Section text begins as a new paragraph Subsection text follows heading on same line. Referencing: (see Section 1) or (see 1.1.2.1). 6
Page Numbers and Spacing Header and Footer Information Include Page Number Options: Spacing Title of document Date Revision number Team name Body is single spaced Paragraphs separated by blank line 7
Lists Bulleted List Numbered Numbered list List with Sublist (1) (1) (2) (a) (3) (b) (2) No punctuation One list per section/subsection 8
Tables and Figures Number each Table or Figure followed by appropriate title. Table 1 Figure 1 Table 2 Figure 2 Table 3 Figure 3 Cite tables and figures in the text by specifying Table or Figure followed by the number. Examples: see Table 6 see Figure 10 9
APPENDIX A: < title > APPENDICES Section and subsections begin with the appendix letter (e.g. A.1, A.1.1, A1.2, etc.) Must be referenced in the body of the document Useful by not essential information not essential does not mean unnecessary! it means not essential for understanding the content in each of the sections! Use appendices for information that does not fit in logically, or only needs to be referenced. 10
Glossary Definitions, Acronyms and Abbreviations Used in the document to save time and space, but only if their meaning is unquestionably clear to the reader. Abbreviations and Acronyms First appearance do not use the abbreviation or acronym Spell it out!...with the abbreviation or acronym in parentheses. e.g. Software Requirements Specification (SRS) document Subsequent references can then use the acronym or abbreviation 11
Format Book Article Reference [3] Citing References [1] Rumbaugh, J., M. Blaha, W. Premerlani, F. Eddy, and W. Lorensen. Object-Oriented Modeling and Design. Englewood Cliffs, NJ: Prentice Hall. 1991. [2] Suchman, L. Representations of Work. Communications ACM 38, 9 (Sept. 1995): 33-34. Institute of Electrical and Electronics Engineers, Inc. IEEE Standard for Developing Software Life Cycle Processes. ANSI/IEEE Std 1074-1991. References are listed in subsection 1.4 of each document. In the body of the document, references should be cited where applicable, with reference number in brackets for example, [1] http://www.mla.org/ 12
Document from a Web Site Author. "Title of Web Page." Title of the Site. Editor. Date and/or Version Number. Name of Sponsoring Institution. Date of Access <URL> Sherman, Chris. "Everything You Ever Wanted to Know About URL." SearchEngineWatch. Ed. Danny Sullivan. 24 Aug. 2004. 4 Sept. 2004 <http://searchenginewatch.com/searchday/article.p hp/3398511>. 13
Standardized Style All documents produced by the team must have the same style the same look and feel to the reader. Standardize Title Page Headers and Footers All of what was described above 14
Myth of the Perfect Draft You can produce a nearly final version of your document in one attempt. Not true!!! At least 50% or your writing time is (should be) re-writing and editing. 15
Revising tips Don t edit as you write Go back a reread is the message clear! Some questions to answer: 1. Is the purpose immediately clear to the reader? 2. Is the message relevant to the reader? 3. Does each new thought make sense? 4. Do the thoughts flow smoothly and logically? 5. Are the thoughts clearly expressed? 16
More Strengthen your message! 1. Is the message complete 2. Are the words appropriate 3. Is the tone correct? and Condense (shorten) your message. 17
Style Using the right tense Clarity Controlled English Sentence length Pompous style Technical terms & jargon Variety and inconsistency Numbers in text Using highlighting Capitalization Colloquialisms & slang Humor Using he or she Using must, should, can, or may Acronyms & abbreviations Punctuation Point of View Find a good technical writing reference text you will learn why you need to use it. 18
Using the right tense Present tense - typical Past tense sometimes when communicating background information Future tense only when describing expected results A READ statement is used to assign the listed variables those values which are obtained from a DATA statement. 19
Active and Passive Voice VOICE: the way the subject (the doer) of the sentence is related to the action expressed by the verb. Examples: Active voice: to the point, sharp and clear PASSIVE: The selection of this operation is made automatically by the software if there is no intervention by the operator. ACTIVE: Unless the operator intervenes, the software selects this function automatically. 20
Active and Passive Voice PASSIVE The program can be started by double clicking on the icon. ACTIVE Double-click on the icon to start the program. Note: Passive voice can be used if the doer in the sentence is unimportant! The sixteen bits of each word are numbered 0 to 15. The I/O units are both shown in Figure 2. The address of the File Control Block becomes the next free location on the stack. 21
Clarity Clear, concise, accurate! Never give an incomplete statement of what the reader has to do. Too much detail is better than too little. KISS Keep it Simple and Straight to the point Simple: avoid compound sentences Reduction through successive refinement is the only path to simplicity. designing the obvious a common sense approach to web application design robert hoekman, jr Search 22
Controlled English: Why Controlled English? Standardizing word usage leads to improved customer acceptance/understanding. For non-english speakers, documents are easier to understand. Lower translation costs. When something is first named, use only that name in subsequent references to that something. Do not add adjectives 23
Sentence Length is Important Use short, simple sentences. Keep length between 13 and 21 words. Read and revise removing unnecessary words. Example You can use TM-BASIC to check that a value entered is within a certain range, to compare data against a value in another data variable, to perform check-digit calculations, or to perform other arithmetic and logical operations. You can use TM-BASIC to: Check that a value entered is within a certain range Compare data against a value in another data variable Perform check-digit calculations Perform other arithmetic and logical operations 24
Pompous Style Redundancy and Padding The result of: Unclear thinking Trying to impress The desire to produce a large volume of work Unwillingness to rewrite!!! Example: Due to the upcoming project submission to support the system upgrade as well as the introduction of the new products, the need is becoming eminent to identify all capital requirements of this process. Your input is important to the resolution of this issue. versus Please supply your capital requirements for support of future system upgrades and introduction of the new products. 25
Using Numbers Write all numbers between zero and twenty as one word. Write numbers thirty, forty, fifty, sixty, seventy, eighty, and ninety as one word. Use hyphens to separate tens and units of numbers like twenty-one. Write numbers above ninety-nine as Arabic numbers (for example, 110). Never split a number across two lines. 26
Highlighting and Capitalization Highlighting text: Never use underlining for emphasis (difficult to read) Bold for main section headings, subsection headings, figure and table titles, emphasis, commands, file and directory names Italics for references to other manuals, symbolic names, variables in command syntax, long pieces of user input Capitalization - Chapter & appendix titles; Section headings - Figure and table names - Acronyms - Entries in a glossary 27
more on Capitalization Leading capital letter Subsection headings References to sections in text All heading entries in Table of Contents Main entries in an index Names of screen fields and menu items 28
Colloquialisms and Commands Colloquialisms (informal, regional), slang and humor don t!!! What about use of (must and should) as opposed to (can and may)? Must means the action is required. Should means that it is advisable. Can implies capability. May is vague, interpreted as meaning permissive / possible. 29
Humor The purpose of technical writing is communication not entertainment What may appear amusing to one reader may prove incomprehensible to a second, and offensive to a third Negatively impacts credibility Reflects on the assumed seriousness (that is, the. professionalism) of those that did the work At best read for the first time, humorous read for the n th time, not 30
He or She? Address your reader directly to avoid use of he or she. Where you think you need to make a choice, rewrite! Examples: If this happens, tell your administrator. He will have to reset your password before you can log-in again. If this happens, ask the system administrator to reset the password and log-in again. Change the workstation database to include the new workstation, and ask him to log-in again. Change the workstation database to include the new workstation, and ask the user to log-in again. 31
Ellipses Punctuation Indicates something is missing from a quotation Indicates section of text has been omitted Colon : Precedes a list Used when connected to the ideas namely:, as follows:, because:, (even if these phrases are not used but can be implied) Semicolon ; Used to separate two clauses which are closely connected. Example: Secretarial is the adjective corresponding to secretary; 32 secretariat is the official establishment of a secretary.
Parentheses More Punctuation Advice Used to add a short remark without interrupting the flow of the sentence. The network addresses (which are specified during installation) cannot be changed. Note. Sometimes hyphens - sort of like this - are used instead. Quotation marks (used for genuine quotations) Use double quotation marks to enclose a quote Use single quotation marks for quotations within a quotation (She said Did you know he said ) 33
Point of View 1 st person singular I write 1 st person plural we write 2 nd person singular you write 2 nd person plural you write 3 rd person singular he, she, one writes 3 rd person plural they wrote (the team wrote) 34