Dilbert © United Feature Syndicate, Inc.. © Keith Vander Linden, 2012 2 Technical Writing ●...
-
Upload
meryl-horton -
Category
Documents
-
view
216 -
download
1
Transcript of Dilbert © United Feature Syndicate, Inc.. © Keith Vander Linden, 2012 2 Technical Writing ●...
![Page 1: Dilbert © United Feature Syndicate, Inc.. © Keith Vander Linden, 2012 2 Technical Writing ● Types Types ● Modes Modes ● Content Content ● Writing Writing.](https://reader036.fdocuments.us/reader036/viewer/2022070407/56649e265503460f94b15f4a/html5/thumbnails/1.jpg)
© Keith Vander Linden, 2012
2
Technical Writing
● Types● Modes● Content● Writing
Nobody reads documentation. – Mark Rettig, CACM, 1991
![Page 2: Dilbert © United Feature Syndicate, Inc.. © Keith Vander Linden, 2012 2 Technical Writing ● Types Types ● Modes Modes ● Content Content ● Writing Writing.](https://reader036.fdocuments.us/reader036/viewer/2022070407/56649e265503460f94b15f4a/html5/thumbnails/2.jpg)
© Keith Vander Linden, 2012
3
Technical Writing: Exercises
● Go to the classroom with your smart phone.
● CS 262 should not be taken.
● The department hates CS 262; it is wildly unpopular.
● Your going to hate CS 262; its to hard.
![Page 3: Dilbert © United Feature Syndicate, Inc.. © Keith Vander Linden, 2012 2 Technical Writing ● Types Types ● Modes Modes ● Content Content ● Writing Writing.](https://reader036.fdocuments.us/reader036/viewer/2022070407/56649e265503460f94b15f4a/html5/thumbnails/3.jpg)
© Keith Vander Linden, 2012
4
Internal Documentation– code prologues– internal comments– self-documenting stuff :
• variable names• structured programming• good object design
![Page 4: Dilbert © United Feature Syndicate, Inc.. © Keith Vander Linden, 2012 2 Technical Writing ● Types Types ● Modes Modes ● Content Content ● Writing Writing.](https://reader036.fdocuments.us/reader036/viewer/2022070407/56649e265503460f94b15f4a/html5/thumbnails/4.jpg)
© Keith Vander Linden, 2012
5
External Documentation– Management documents:
• risk management plan• project plan• SQA plan
– Conventional SE documents:
• system specification• requirements document• design document (various
levels)• test plan (various levels)
– Users documentation:• installation guides• tutorials• user's guides• reference guides• super index• on-line help
![Page 5: Dilbert © United Feature Syndicate, Inc.. © Keith Vander Linden, 2012 2 Technical Writing ● Types Types ● Modes Modes ● Content Content ● Writing Writing.](https://reader036.fdocuments.us/reader036/viewer/2022070407/56649e265503460f94b15f4a/html5/thumbnails/5.jpg)
© Keith Vander Linden, 2012
6
sanity check...
● Projects produce loads of documentation.● Is this a waste of paper and of time?
![Page 6: Dilbert © United Feature Syndicate, Inc.. © Keith Vander Linden, 2012 2 Technical Writing ● Types Types ● Modes Modes ● Content Content ● Writing Writing.](https://reader036.fdocuments.us/reader036/viewer/2022070407/56649e265503460f94b15f4a/html5/thumbnails/6.jpg)
© Keith Vander Linden, 2012
9
Modes of Documentation
● In-line code comments● Paper documents● Hypertext manuals● On-line help systems● Video demonstrations● Reference cards● Help desks
![Page 7: Dilbert © United Feature Syndicate, Inc.. © Keith Vander Linden, 2012 2 Technical Writing ● Types Types ● Modes Modes ● Content Content ● Writing Writing.](https://reader036.fdocuments.us/reader036/viewer/2022070407/56649e265503460f94b15f4a/html5/thumbnails/7.jpg)
© Keith Vander Linden, 2012
10
JavaDoc
● Javadoc generates API documentation in HTML format from doc comments in Java source code.
![Page 8: Dilbert © United Feature Syndicate, Inc.. © Keith Vander Linden, 2012 2 Technical Writing ● Types Types ● Modes Modes ● Content Content ● Writing Writing.](https://reader036.fdocuments.us/reader036/viewer/2022070407/56649e265503460f94b15f4a/html5/thumbnails/8.jpg)
© Keith Vander Linden, 2012
11
On-Line Help
● On-line documentation is (or can be):– there all the time– context sensitive– great for brief reminders
● …but it’s also:– no better than paper and may well be worse.
● On-line documentation is fundamentally different from paper.
![Page 9: Dilbert © United Feature Syndicate, Inc.. © Keith Vander Linden, 2012 2 Technical Writing ● Types Types ● Modes Modes ● Content Content ● Writing Writing.](https://reader036.fdocuments.us/reader036/viewer/2022070407/56649e265503460f94b15f4a/html5/thumbnails/9.jpg)
© Keith Vander Linden, 2012
12
Constraints for On-Line Text
● Use dark text on a light background.● Be consistent with the application.● Give navigation facilities:
– forward/back– TOC
● Lines should be no longer than 60 characters.
● Capital letters should be >= 3mm tall.
![Page 10: Dilbert © United Feature Syndicate, Inc.. © Keith Vander Linden, 2012 2 Technical Writing ● Types Types ● Modes Modes ● Content Content ● Writing Writing.](https://reader036.fdocuments.us/reader036/viewer/2022070407/56649e265503460f94b15f4a/html5/thumbnails/10.jpg)
© Keith Vander Linden, 2012
13
User Documentation
● A class of documentation aimed at the user of the software.
● Users judge the quality of your system in part on it.
● Unfortunately, it has a bad reputation.
![Page 11: Dilbert © United Feature Syndicate, Inc.. © Keith Vander Linden, 2012 2 Technical Writing ● Types Types ● Modes Modes ● Content Content ● Writing Writing.](https://reader036.fdocuments.us/reader036/viewer/2022070407/56649e265503460f94b15f4a/html5/thumbnails/11.jpg)
© Keith Vander Linden, 2012
14
User Guide
● Task-centered documentation● Should contain:
– explicit examples– expected feedback– concise overviews with hyperlinks to
details
![Page 12: Dilbert © United Feature Syndicate, Inc.. © Keith Vander Linden, 2012 2 Technical Writing ● Types Types ● Modes Modes ● Content Content ● Writing Writing.](https://reader036.fdocuments.us/reader036/viewer/2022070407/56649e265503460f94b15f4a/html5/thumbnails/12.jpg)
© Keith Vander Linden, 2012
15
Reference Guide
● Lists all the commands:– alphabetically (good for command-line
interfaces)– hierarchically (better for shallow GUIs)
● Optional, but good for advanced users/administrators
![Page 13: Dilbert © United Feature Syndicate, Inc.. © Keith Vander Linden, 2012 2 Technical Writing ● Types Types ● Modes Modes ● Content Content ● Writing Writing.](https://reader036.fdocuments.us/reader036/viewer/2022070407/56649e265503460f94b15f4a/html5/thumbnails/13.jpg)
© Keith Vander Linden, 2012
16
Super Index
● Indexes basic terms for the system● Vocabulary problem:
– Choosing names is hard– Multilingually, it's even harder– Use an index with multiple terms
![Page 14: Dilbert © United Feature Syndicate, Inc.. © Keith Vander Linden, 2012 2 Technical Writing ● Types Types ● Modes Modes ● Content Content ● Writing Writing.](https://reader036.fdocuments.us/reader036/viewer/2022070407/56649e265503460f94b15f4a/html5/thumbnails/14.jpg)
© Keith Vander Linden, 2012
18
John M. CarrollThe minimal manual
● The Nurnberg Funnel, 1990
● Minimalist Instruction:– Allow learners to start using
the system immediately.– Reduce the amount of
reading.– Make errors less traumatic
and more instructive.
Images from www.cs.vt.edu, Apr, 2004
Der Nurnberger Trichter
![Page 15: Dilbert © United Feature Syndicate, Inc.. © Keith Vander Linden, 2012 2 Technical Writing ● Types Types ● Modes Modes ● Content Content ● Writing Writing.](https://reader036.fdocuments.us/reader036/viewer/2022070407/56649e265503460f94b15f4a/html5/thumbnails/15.jpg)
© Keith Vander Linden, 2012
19
The Writing Proper
● Writing for the technical industry● Topics:
– Audience analysis– Basic Grammar– Basic Style
● Hints:– Revise, revise, revise– Get someone to proofread it for you
![Page 16: Dilbert © United Feature Syndicate, Inc.. © Keith Vander Linden, 2012 2 Technical Writing ● Types Types ● Modes Modes ● Content Content ● Writing Writing.](https://reader036.fdocuments.us/reader036/viewer/2022070407/56649e265503460f94b15f4a/html5/thumbnails/16.jpg)
© Keith Vander Linden, 2012
20
Audience Analysis● Audience types for technical writing:
– Experts
– Technicians
– Executives/managers
– Non-specialists (of various grades)
● This may seem obvious, but it is critical.
![Page 17: Dilbert © United Feature Syndicate, Inc.. © Keith Vander Linden, 2012 2 Technical Writing ● Types Types ● Modes Modes ● Content Content ● Writing Writing.](https://reader036.fdocuments.us/reader036/viewer/2022070407/56649e265503460f94b15f4a/html5/thumbnails/17.jpg)
© Keith Vander Linden, 2012
21
Grammar for Technical Writing
● agreement● anaphora ● attachment problems● articles● split infinitives
![Page 18: Dilbert © United Feature Syndicate, Inc.. © Keith Vander Linden, 2012 2 Technical Writing ● Types Types ● Modes Modes ● Content Content ● Writing Writing.](https://reader036.fdocuments.us/reader036/viewer/2022070407/56649e265503460f94b15f4a/html5/thumbnails/18.jpg)
© Keith Vander Linden, 2012
22
Agreement
● When the set of windows {is/are} closed, ...
● The flavor of youth - its trials, its joys, its challenges - {is/are} not soon forgotten. - Strunk & White, Elements of Style
![Page 19: Dilbert © United Feature Syndicate, Inc.. © Keith Vander Linden, 2012 2 Technical Writing ● Types Types ● Modes Modes ● Content Content ● Writing Writing.](https://reader036.fdocuments.us/reader036/viewer/2022070407/56649e265503460f94b15f4a/html5/thumbnails/19.jpg)
© Keith Vander Linden, 2012
23
Pronouns
● The harder the teachers tried to explain the material to the students, the quieter they got. - E231, U. Washington
● Tom told James that he had won the lottery. - ibid
![Page 20: Dilbert © United Feature Syndicate, Inc.. © Keith Vander Linden, 2012 2 Technical Writing ● Types Types ● Modes Modes ● Content Content ● Writing Writing.](https://reader036.fdocuments.us/reader036/viewer/2022070407/56649e265503460f94b15f4a/html5/thumbnails/20.jpg)
© Keith Vander Linden, 2012
24
Pronouns: Example 1 "The Last Supper" is painted on the
dilapidated wall of what was a little chapel attached to the main church in ancient times, I suppose. It is battered and scarred in every direction, and stained and discolored by time, and Napoleon's horses kicked the legs off most the disciples when they (the horses, not the disciples) were stabled there more than half a century ago. - The Innocents Abroad, Mark Twain
![Page 21: Dilbert © United Feature Syndicate, Inc.. © Keith Vander Linden, 2012 2 Technical Writing ● Types Types ● Modes Modes ● Content Content ● Writing Writing.](https://reader036.fdocuments.us/reader036/viewer/2022070407/56649e265503460f94b15f4a/html5/thumbnails/21.jpg)
© Keith Vander Linden, 2012
26
Attachment
● I saw the Grand Canyon flying to New York.
● I saw the dog on a hill with a telescope.
![Page 22: Dilbert © United Feature Syndicate, Inc.. © Keith Vander Linden, 2012 2 Technical Writing ● Types Types ● Modes Modes ● Content Content ● Writing Writing.](https://reader036.fdocuments.us/reader036/viewer/2022070407/56649e265503460f94b15f4a/html5/thumbnails/22.jpg)
© Keith Vander Linden, 2012
27
Articles
● open dialog box
![Page 23: Dilbert © United Feature Syndicate, Inc.. © Keith Vander Linden, 2012 2 Technical Writing ● Types Types ● Modes Modes ● Content Content ● Writing Writing.](https://reader036.fdocuments.us/reader036/viewer/2022070407/56649e265503460f94b15f4a/html5/thumbnails/23.jpg)
© Keith Vander Linden, 2012
28
Split Infinitives
● to boldly go where no one has gone before
![Page 24: Dilbert © United Feature Syndicate, Inc.. © Keith Vander Linden, 2012 2 Technical Writing ● Types Types ● Modes Modes ● Content Content ● Writing Writing.](https://reader036.fdocuments.us/reader036/viewer/2022070407/56649e265503460f94b15f4a/html5/thumbnails/24.jpg)
© Keith Vander Linden, 2012
29
Style for Technical Writing
● active/passive● wordiness● stilted language● negatives● context● lists● consistency
![Page 25: Dilbert © United Feature Syndicate, Inc.. © Keith Vander Linden, 2012 2 Technical Writing ● Types Types ● Modes Modes ● Content Content ● Writing Writing.](https://reader036.fdocuments.us/reader036/viewer/2022070407/56649e265503460f94b15f4a/html5/thumbnails/25.jpg)
© Keith Vander Linden, 2012
30
Active/Passive· Depress knob and hold for 60 seconds
after pilot has been lighted. Release knob and turn to On position. - the furnace example
· Chapter IV, in which it is shown that Tiggers don't climb trees - The house at Pooh Corner A. Milne
· Parents - Socks must be worn while in Ronald’s Play Place. Thank You - McDonalds Co.
![Page 26: Dilbert © United Feature Syndicate, Inc.. © Keith Vander Linden, 2012 2 Technical Writing ● Types Types ● Modes Modes ● Content Content ● Writing Writing.](https://reader036.fdocuments.us/reader036/viewer/2022070407/56649e265503460f94b15f4a/html5/thumbnails/26.jpg)
© Keith Vander Linden, 2012
31
Wordiness· Owing to the fact that the notion of Artificial
Intelligence is poorly defined, there is no doubt but that it is a loosely knit field.
![Page 27: Dilbert © United Feature Syndicate, Inc.. © Keith Vander Linden, 2012 2 Technical Writing ● Types Types ● Modes Modes ● Content Content ● Writing Writing.](https://reader036.fdocuments.us/reader036/viewer/2022070407/56649e265503460f94b15f4a/html5/thumbnails/27.jpg)
© Keith Vander Linden, 2012
32
Wordiness
Vigorous writing is concise. A sentence should contain no unnecessary words, a paragraph no unnecessary sentences, for the same reason that a drawing should have no unnecessary lines and a machine no unnecessary parts. This requires not that the writer make all his sentences short, or that he avoid all detail and treat his subjects only in outline, but that every word tell. - see Strunk's text on omitting needless words.
![Page 28: Dilbert © United Feature Syndicate, Inc.. © Keith Vander Linden, 2012 2 Technical Writing ● Types Types ● Modes Modes ● Content Content ● Writing Writing.](https://reader036.fdocuments.us/reader036/viewer/2022070407/56649e265503460f94b15f4a/html5/thumbnails/28.jpg)
© Keith Vander Linden, 2012
33
Stilted language
· We utilized said methodology.
![Page 29: Dilbert © United Feature Syndicate, Inc.. © Keith Vander Linden, 2012 2 Technical Writing ● Types Types ● Modes Modes ● Content Content ● Writing Writing.](https://reader036.fdocuments.us/reader036/viewer/2022070407/56649e265503460f94b15f4a/html5/thumbnails/29.jpg)
© Keith Vander Linden, 2012
34
Negatives
· Don't use negative imperatives.
![Page 30: Dilbert © United Feature Syndicate, Inc.. © Keith Vander Linden, 2012 2 Technical Writing ● Types Types ● Modes Modes ● Content Content ● Writing Writing.](https://reader036.fdocuments.us/reader036/viewer/2022070407/56649e265503460f94b15f4a/html5/thumbnails/30.jpg)
© Keith Vander Linden, 2012
35
Context· When you have chosen a filename, click
on the save button.
· Click on the OK button. The system indicates that it is finished by printing "File Saved...".
![Page 31: Dilbert © United Feature Syndicate, Inc.. © Keith Vander Linden, 2012 2 Technical Writing ● Types Types ● Modes Modes ● Content Content ● Writing Writing.](https://reader036.fdocuments.us/reader036/viewer/2022070407/56649e265503460f94b15f4a/html5/thumbnails/31.jpg)
© Keith Vander Linden, 2012
36
Lists· Use lists to make the structure clear. · Enumerate ordered sequences of actions.
![Page 32: Dilbert © United Feature Syndicate, Inc.. © Keith Vander Linden, 2012 2 Technical Writing ● Types Types ● Modes Modes ● Content Content ● Writing Writing.](https://reader036.fdocuments.us/reader036/viewer/2022070407/56649e265503460f94b15f4a/html5/thumbnails/32.jpg)
© Keith Vander Linden, 2012
37
Consistency· Parallel lists should have parallel
grammar. · Documents should have a standard style
and format throughout.