Technical Writing. Computer Science and Engineering College of Engineering The Ohio State University. Lecture 12

Transcription

1 Technical Writing Computer Science and Engineering College of Engineering The Ohio State University Lecture 12

2 High-level Parallels Software Engineering Requirements Analysis Design Implementation Testing Debugging Technical Writing Analysis Prewriting Composition Reviewing Revising

3 High-level Parallels Software Engineering Requirements Analysis Design Implementation Testing Debugging Technical Writing Analysis Prewriting Composition Reviewing Revising

4 Composing the Document The better the preparation in prewriting, the easier it is to write the document itself Regardless, it is still work Takes skill, practice, experience, motivation, and tools

5 Doc. Component Engineering Similarity: Large software systems are made up of smaller components (of code) Large documents are made up of smaller components (of prose) Component = section of the document Often has its own heading Large component can contain other smaller ones Choice of components driven by prewriting (eg outline)

6 Advantages of Components Having to write the whole document is too intimidating Obvious milestones for completion Reduces panic since you know where you stand Permits time budgeting Reduces writing to a more step-bystep process Instant gratification Easy cure for writer s block: work on a different section

7 Writing a Component Prerequisite: Know the purpose Have the information Composition strategies: Write draft using full sentences Jot down points as sentence fragments, then flesh out into full sentences Free-form combination of sentences, fragments, phrases, words

8 Overcoming Writer s Block Start anywhere Do more prewriting Research Revise outline or organization Draw pictures of structure, flow Explain it to someone else (verbally) Work on a different section Motivation Imagine life when you are done! Set an impossible schedule, then panic Change of environment Take a break

9 Rhetorical Patterns Well-established pattern of exposition Ready-made scaffolding into which specific information can be inserted Exist in every culture or group Advantages The reader is already familiar with the pattern The technical writer does not have the time (or skill) to invent new scaffolding

10 General-to-Specific Pattern Often used for introductory sections Start with the most general statement More computing resources are devoted to the management of data than to any other task. Gradually get more specific This application streamlines the processing of spatial trajectory data, enabling rich real-time interactions with the data set. Build to most specific statements

11 Classification Pattern Often used for definitions and listings Organizes information by dividing it into distinct, non-overlapping categories Example: Installation, initialization, data entry, selection, access control, Within each category, information is presented in a similar way (parallel structure) Example: Purpose, prerequisites, results, error messages, alternatives, references,

12 Comparison-Contrast Pattern For point-by-point comparisoncontrast, consider each aspect in turn In football, the ball may be thrown forward. In rugby, however, only lateral passes are allowed. In football, play ends when the ballcarrier is tackled, while in rugby play continues after the tackle. The tackled player, however, must release the ball.

13 Comarison-Contrast Pattern For whole-to-whole comparisoncontrast, consider top-level distinction To create a new object (zack) from the command line: Type edit zack at the command prompt Fill in the attributes of the presented wizard Select Save from the File menu To create a new object (zack) from within the application: Select New from the File menu Fill in the attributes of the presented wizard Select Save As from the File menu, and enter zack.

14 Definition Pattern Typically short and simple Place term in an established category, then distinguish it from other terms in that category Undo is a function that restores an object its state immediately prior to the last operation. Coffee is a drink made from the roasted and ground beanlike seeds of a tropical shrub.

15 Other Patterns Ascending/Descending order Order items in terms of a single criteria such as importance, cost, frequency, time, etc Narration Order items in which things happen according to a consistent point of view Cause-and-effect List of error messages, but includes cause(s) for the error to occur

16 Component Assembly Add headings (part, chapter, section ) Add transitions to prompt the reader Firstly, secondly, Now, then, soon thereafter, immediately For example, that is, Moreover, similarly, further, However, on the other hand, otherwise, Therefore, thus, as a consequence, In conclusion, in summary, finally

17 Drafting Preliminary draft Starting is always difficult, easier if it s just a draft Do not worry about spelling, grammar, form Focus on sound expression of key ideas Middle draft Refine organization Flesh out content Modify, cut, paste, move things around Final draft Spelling, grammar, word choice, pagination

18 High-level Parallels Software Engineering Requirements Analysis Design Implementation Testing Debugging Technical Writing Analysis Prewriting Composition Reviewing Revising

19 Reviewing Easy to become attached to prose we have written Flow seems natural; we know what is coming next! Having someone else check your work Similar to testing in software Check Amount of detail (verbose vs terse) Formality (casual vs rigid) Tone (distant vs neutral, warm, familiar) Consistency

20 Red Flag: Inconsistent View Changing from 2 nd to 3 rd person Limit your inbox to 5 GB. If more space is needed, the user can submit a help request. Limit your inbox to 5 GB. For more space, submit a help request.

21 Red Flag: Passive Voice The verb expresses what is done to the subject (by someone or something) Occasional use is OK Sometimes even preferred for scientific documents Excessive use creates a detached tone and can weaken your writing The error is used by the loader to indicate The loader issues this error to indicate

22 Red Flag: Wordiness In the final analysis, the end result of excessive verbiage in a document is increased cost in terms of pages of paper, bytes on a disk, and inefficient use of the reader s time and writer s effort. Words cost money. A shorter book is more efficient and effective than a long one.

23 Red Flag: Faulty Parallelism The use of different grammatical structures in a parallel structure Steps for using the app: Preparing for installation Configuration Do you want the advanced options?

24 Red Flag: Dangling Modifier The use of a verbal phrase that does not connect (or modify) anything else in the sentence. After typing enter, the system will continue with the second pass of the assembler. Specific instance: Beginning sentence with This Better to add noun immediately after this to make the modified thing explicit

25 Red Flag: End with Preposition Prepositions begin phrases With, at, from, into, during, for, by Common advice: never end a sentence with a preposition This advice is ignored in spoken English Not really a rule in written English either Winston Churchill: That is criticism up with which I will not put.

26 Red Flag: Splitting a Verb Dogma: Avoid splitting an infinitive to + verb, or will + verb Avoid putting an adverb inside Patients should try to, if possible, avoid going up and down stairs It s five year mission, to boldly go Famous over-use of dogma: Chief Justice Roberts swearing in Obama will execute the office of the president of the United States faithfully

27 Red Flag: Sexist Language Diversity in readership should be reflected in the text: Pronouns Names Genders Ages Race Ethnicities

28 Red Flag: Which vs That Rule: Use which for non-restrictive subordinate clauses Use that for restrictive ones Example: Ed s country house, which is located on five acres, had bats in the attic The house that sat on the hill had bats in the attic Advice: do a search for which

29 Red Flag: Utilize Why would anyone utilize a longer word when a shorter word would do?

30 High-level Parallels Software Engineering Requirements Analysis Design Implementation Testing Debugging Technical Writing Analysis Prewriting Composition Reviewing Revising

31 Revising Revising is when bad writing becomes good writing Rule: First version is always bad Accept it, and be prepared to rewrite Add better flow, transitions Reduce wordiness Clarify obscure points

32 Examples from Design Review The component type which contains the math definition of the component is stored in the file called Type.h which provides the client with the general component description.

33 If users input a file has invalid header record which contains more than 13 characters, the program will pop up an error message: Parse Error: Invalid header record, then it terminates.

34 The overall is contained in Machine_Program.cpp

35 If the user wishes to quit, then a q will be entered.

36 The function will return 0 if successful, and an integer value if an error of any type is recorded.

37 So now your wondering how these classes will work together? Well it s pretty simple these classes will extend the functionality of Score.java and Error.java. So, what does that mean? Well, it means that

38 Bottom Line Technical writing requires work, practice, skill, technique, time; not talent The first draft is always bad writing; allow time (and energy) for revisions There is no substitute for having something to say; you can not bluff it