Your SlideShare is downloading. ×
Introduction to Technical Writing
Upcoming SlideShare
Loading in...5
×

Thanks for flagging this SlideShare!

Oops! An error has occurred.

×

Introducing the official SlideShare app

Stunning, full-screen experience for iPhone and Android

Text the download link to your phone

Standard text messaging rates apply

Introduction to Technical Writing

4,511
views

Published on

Vince Ricci, University of Tokyo, Center for Innovation in Engineering Education (CIEE). …

Vince Ricci, University of Tokyo, Center for Innovation in Engineering Education (CIEE).
Please check out the course blog here
http://techwritingtodai.blogspot.com
Special thanks Morimura-sensei, Mr. Entzinger and the CIEE staff.

Published in: Education, Business

4 Comments
8 Likes
Statistics
Notes
  • fantastic,
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • November 2010 audio is here
    http://www.archive.org/details/IntroductionToTechnicalWriting2010November
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • I uploaded audio from the first half of the May 2010 lecture here
    http://www.archive.org/details/IntroductionToTechnicalWriting
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • I just updated the course website (blog).
    Please find it here
    http://techwritingtodai.blogspot.com/
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
No Downloads
Views
Total Views
4,511
On Slideshare
0
From Embeds
0
Number of Embeds
1
Actions
Shares
0
Downloads
395
Comments
4
Likes
8
Embeds 0
No embeds

Report content
Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
No notes for slide
  • Good afternoon. I am Vince Ricci. It is my honor to be here at University of Tokyo, Center for Innovation in Engineering Education (CIEE). This is English for Engineers and Scientists, Section A. I am going to spend the next 100 minutes giving an Introduction to Technical Writing in English. Special thanks Morimura-sensei, Mr. Entzinger and entire staff of CIEE. I enjoy this event and want to thank you all for being here today.
  • Stanford B.A., History June 1992James Lyons Award for ServiceAwarded Public Service Summer Fellowship to write & edit National Guide to Fundraising & Development
  • NYU M.A., Educational Communication & Technology (ECT) December 2000Cognitive Science, Instructional DesignThen speak anecdote re. how I came to Japan. Plug “Diaspora”?
  • Writing teacher since 1990Louisiana Distinguished Teacher Award at most prestigious private school in Southeastern U.S.Secured steady funding by writing winning grant proposals for U.S. Government plus major corporations
  • Admissions counselor since 2002Helped over 400 clients write thousands of essaysAdmitted to every top school5 will attend HBS from 2010
  • We have 100 mins totalWill be ending at 18:10I will try to leave time for questions at endAlso hope you have questions in middleSeveral times I will ask you to raise your handsKeeps us all awake during these long afternoons
  • Kaplan Technical Writing: A Resource for Technical Writers at All Levels By Carrie Hannigan, Diane Martinez, Carrie Wells, Tanya Peterson, Carolyn Stevenson
  • Hereafter, “Kaplan”
  • CHAPTER 1
  • WHAT IS TECHNICAL WRITING?
  • Technical writing is informative writing, which involves technical, scientific, and engineering-based topicsQuick poll of the audienceHow many Engineering students?
  • Here are some tasks done by Technical communicators: First, we write and edit user manuals. Most of you research and write grants and proposals, and deliver presentations. Much respect to John Freeman. I heard he gave a great lecture on presentations a few weeks ago.Quick note re. ESL issues. Much respect! I assume you are decent tech communicators in your native tongue. Raise hands if native language is not English. Is it Japanese? Thanks for efforts!
  • Technical writing is designed to convey information of a complex nature to a specific audience
  • If the audience cannot understand or use the information presented, the writer has failed in his or her purpose
  • Fail!
  • Good technical writing is accurate, clear, and concise
  • Clear
  • ACCURACY
  • Inaccurate technical documents can result in very real physical, financial, or environmental repercussions. Anecdote - NASA Genesis space mission; probe crashed to earth because design documentation failed to specify proper way to install parachutes. More recently, BP oil spill in Gulf of Mexico (two robots crashed into each other and knocked out the plug)
  • A word on CLARITY
  • If a report does not contain clear information, the reader cannot comprehend the writer's intent or follow instructions
  • Finally, the authors third point, CONCISENESS follows ACCURACY and CLARITY in the list of critical factors for technical writing. CONCISE simply means brief, short, direct.
  • Technical writing is characterized by direct language that gets right to the point;It avoids flowery descriptions that can obscure meaning. I think you get the point here. Technical writing is not poetry.
  • When in doubt, cut it out
  • Technical writing is goal-oriented; its goal is to convey information.The reader should not have to shift through extraneous material to find essential information
  • The various types of technical documents all have a specific format that allows the reader to quickly locate everything the reader or listener needs in an organized fashion
  • Now, I just said that Technical writing is not poetry, but that does not make it crude or ugly. In fact, technical writing is beautiful in its simplicity. It is sophisticated content conveyed in a clean and usable way
  • clarity
  • Kaplan Technical Writing(“Kaplan”)
  • Equally important is the technical writer's understanding of purpose
  • audience
  • and context
  • To be an effective technical communicator the writer must consider the purpose of the document, the intended audience and the context in which the writer is writing or presenting
  • PurposeAudienceContext
  • To take these 3 things into account will directly affect the effectiveness of the technical document
  • If the audience cannot use, apply or understand the information presented then the author has failed
  • Fail!
  • Because technical communication has set specific goals and requirements, the technical communicator must have a plan for success
  • PURPOSE:The first consideration should be the purpose of the document or presentation
  • What is the ultimate goal of the communication?Quick poll – what is your ultimate goal here today? Why are you here? how many of you need to write something in English? First time for you? Scared?
  • Technical communication is generally designed to be practical
  • Purpose determines format or style
  • Next,DEFINE THE AUDIENCE
  • Knowing the audience is the key to any successful technical communication
  • If the audience is known the writer can tailor the communication to meet the needs of that audience
  • Is the audience technically savvy or composed of lay (non-technical) people? If you know your audience, you can address them appropriately
  • The writer uses different language when addressing a technical expert as opposed to addressing an audience that has limited knowledge
  • To summarize, remember these three points. First, ask yourself who are your intended readers?
  • Second, considerWhat would audience members be doing with the information?
  • Finally,try to consider the knowledge level of the audience
  • Next, we will discuss our third point in this series. After Purpose and Audience, you as the writer must consider CONTEXT
  • Context largely determines how the reader or listener will receive and interpret the message
  • Thinking about context will help the writer determine what format is appropriate and how the subject should be approached. To use today’s lecture as an example, I had to consider the fact that this class comes in the middle of the course. I tried to learn what information you already received when framing this presentation.
  • Failing to consider context may result in the message being rejected, particularly if the goal is to persuade
  • So, to sum up. As a technical writer, your goals areAccuracyClarityConciseness
  • You are likely to achieve those goals if you rememberPurposeAudienceContext
  • Kaplan Technical Writing(“Kaplan”)
  • Hereafter, “Kaplan”
  • After this class, you will read chapter 3 online.
  • That is your homework. More about that at the end of today.
  • Writing Tips for PhD StudentsPOLL – any of you Ph.D. students?Does not matter. This article applies to any technical writer. In fact, it is required reading for my clients, who are applying to MBA programs. It is simply the best writing advice I know b/c it is accurate, clear and concise. Let’s take a look.
  • John H. Cochrane, Graduate School of Business (Booth),University of ChicagoI was just on campus visiting former clients and meeting admissions directorDid not meet Professor Cochrane, but would love to do so in the future
  • John H. Cochrane, Graduate School of Business (Booth),University of Chicago
  • Image of Booth Hyde ParkHarper Center
  • 1. ORGANIZATION
  • Figure out the one central and novel contribution of your paper. Write this down in one paragraph. As with all your writing, this must be concrete. THIS IS COCHRANE’S PUNCHLINE, HIS MAIN POINT. IT IS THE FIRST SENTENCE OF HIS ARTICLE. HE IS FOLLOWING HIS OWN ADVICE. THIS IS ALSO THE MAIN POINT OF TODAY’S LECTURE. PLEASE CIRCLE THIS SLIDE ON YOUR HANDOUTS.
  • I use Cochraneb/c he is concrete. I like Kaplan, but first two chapters are somewhat abstract since they cover technical writing theory. Cochrane gives many examples of what NOT to do. Here he says: Don’t write “I analyzed data on executive compensation and found many interesting results.”
  • Explain what the central results are.
  • For example, Fama and French 1992 start their abstract with TOUGH SENTENCE. THE HARDEST THING YOU WILL READ TODAY. BUT I WILL HELP YOU.
  • “Two easily measured variables, size and book-to-market equity, combine to capture the cross-sectional variation in average stock returns associated with market β, size, leverage, book-to-market equity, and earnings-price ratios.”
  • “Two easily measured variables, size and book-to-market equity
  • combine to capture the cross-sectional variation
  • in average stock returns
  • associated with market β, size, leverage, book-to-market equity, and earnings-price ratios.”
  • “Two easily measured variables, size and book-to-market equity, combine to capture the cross-sectional variation in average stock returns associated with market β, size, leverage, book-to-market equity, and earnings-price ratios.”
  • Distilling your one central contribution will take some thought.
  • It will cause some pain, because you will start to realize how much you’re going to have to throw out.
  • Once you do it, though, you’re in a much better position to focus the paper on that one contribution, and help readers to get it quickly.
  • Your readers are busy and impatient. BACK TO KAPLAN’S POINT ABOUT AUDIENCE.
  • No reader will ever read the whole thing from start to finish. PERHAPS THAT IS A BIT EXTREME. BUT I TELL MY CLIENTS THE SAME THING. you cannot expect them to read it all. You are competing for limited resources. What you send will be read, but perhaps not with any interest.
  • Readers skim. You have to make it easy for them to skim. (I tell my clients that a reader will spend 10-20 seconds on a resume. You spend HOURS!) Skim means “read as fast as possible for main ideas. Skip the details. I suspect many of you skim when you read Japanese.
  • Most readers want to know your basic result.
  • Only a few care how it is different from others.
  • Organize the paper in “triangular” or “newspaper” style, not in “joke” or “novel” style.
  • Notice how newspapers start with the most important part, then fill in background later for the readers who kept going and want more details. (do you even make it past the headlines?)
  • “triangular” style means that the main idea comes first. A fellow counselor tells his clients to put the end at the beginning. This counselor is a journalist by training (Fulbright Fellow with a Masters from UC Berkeley). Then, you can explain the context at the end
  • Think of this as what and how.Write WHAT you thinkBefore explaining WHY you think it and HOW you found that answer
  • A good joke or a mystery novel has a long windup to the final punchline. (Punchline  Main point)
  • put the punchline right up front and then slowly explain the joke. Readers don’t stick around to find the punchline in Table 12.
  • (Most writers) get this exactly wrong, and we never really find out what the contribution of the paper is until the last page, the last table, and the last 5 minutes of the seminar.
  • Often, my clients’ first drafts are written in a funnel style, with the main idea at the end.
  • I often read essays where the writer explains why he believes something, and how he found his answer. As a reader, I am not interested in why and how until I know if WHAT he was to say (his conclusion or main point) is in fact interesting, new, valuable.
  • A good paper is not a travelogue of your search process. We don’t care how you came to figure out the right answer.
  • We don’t care how you came to figure out the right answer. We don’t care about the hundreds of things you tried that did not work. Save it for your memoirs. (e.g. Thomas Edison and the light bulb.)
  • Contribution firstReaders skimTriangular styleOpen with punchline (put the end at the beginning)
  • Your Abstract
  • Most journals allow 100-150 words. Obey this limit now.
  • The main function of the abstract is to communicate the one central and novel contribution, which you just figured out.
  • You should not mention other literature in the abstract.
  • Like everything else, the abstract must be concrete.
  • Say what you find, not what you look for.
  • Don’t write “data are analyzed, theorems are proved, discussion is made.”
  • Your Introduction
  • The introduction should start with what you do in this paper, the major contribution. You must explain that contribution so that people can understand it.
  • Don’t just state your conclusion: “My results show that the pecking-order theory is rejected.”
  • Give the fact behind that result. “In a regression of x on y, controlling for z, the coefficient is q.”
  • The first sentence is the hardest.
  • “Two easily measured variables, size and book-to-market equity, combine to capture the cross-sectional variation in average stock returns associated with market β, size, leverage, book-to-market equity, and earnings-price ratios.”
  • Do not start with philosophy, “Financial economists have long wondered if markets are efficient.”
  • Do not start with “The finance literature has long been interested in x.”
  • Your paper must be interesting on its own, and not just because lots of other people wasted space on the subject.
  • Do not start with a long motivation of how important the issue is to public policy. It’s a waste of space.
  • Start with your central contribution.
  • “Two easily measured variables, size and book-to-market equity, combine to capture the cross-sectional variation in average stock returns associated with market β, size, leverage, book-to-market equity, and earnings-price ratios.”
  • How do you add value?
  • A contribution includes an addition to your field’s overall knowledge
  • Three pages is a good upper limit for the introduction.
  • Abstract - no literature reviewIntroduction - first sentenceStart with contribution
  • Your literature review
  • Do not start your introduction with a page and a half of other literature.
  • Returning to our funnel metaphor, this is like putting the ideas of others before your own. This is the not the place to be humble. Can you show confidence in your new idea? What are you contributing to your field? IMAGE of a soldier in battle holding a human shield to catch arrows or bullets. It is cowardly. Be confident!
  • First, your readers are most interested in just figuring out what you do.
  • They can’t start wondering if it’s better than what others have done until they understand what you do.
  • Second, most readers do not know the literature
  • It’s going to be hard enough to explain your paper in simple terms; WHY do you want to explain everyone else’s too.
  • After you’ve explained your contribution, then you can write a brief literature review.
  • Make it a separate section so people can skip if not interested
  • Remember, it will be very hard for people to understand how your paper is different from others’ given that they don’t understand your paper yet, and most of them have not read the other papers.
  • Remember, put the end at the beginning
  • The WHAT before the WHY and HOW
  • Be selfish! (anecdote of t-shirt in Ikebukuro)
  • Having said that, you can and should remember to be generous in your citations. As you explain your contribution, give credit where credit is due.
  • You do not have to say that everyone else did it all wrong for your approach and improvements to be interesting.
  • The main point of the literature review should be to set your paper off against the 2 or 3 closest current papers, and to give proper credit to people who deserve priority for things that might otherwise seem new in your paper.
  • Body of the paper
  • Your task now is to get to the central result as fast as possible. CENTRAL RESULT = MAIN RESULT = CONTRIBUTION = MAIN POINT = PUNCHLINE.
  • Most papers do precisely the opposite: They have a long motivation, a long literature review, a big complex model that then gets ignored, descriptive statistics, preliminary results, a side discussion or two and then finally Table 12 of “main estimates.”
  • By then we’re all asleep.
  • Do better!
  • Here’s the rule: There should be nothing before the main result that a reader does not need to know in order to understand the main result.MAIN RESULT = CONTRIBUTION = MAIN POINT = PUNCHLINE.
  • Conclusions should be short and sweet.
  • Do not restate all of your findings.
  • One statement in the abstract, one in the introduction and once more in the body of the text should be enough! That means you can write a 3 sentence conclusion.
  • You can include a short paragraph or two acknowledging limitations, suggesting implications beyond those in the paper
  • Keep it short though — don’t write your grant application here outlining all of your plans for future research. Since 1992, I have told my students to NEVER exceed the scope of the paper in the conclusion. The conclusion summarizes what you have already written. It does not discuss what you will write in the future. No new ideas in the conclusion.
  • Don’t speculate; the reader wants to know your facts not your opinions.
  • Literature review – meaningless before your contributionBody of the paper – all about your main resultShort conclusion
  • 2 Writing
  • Keep the paper as short as possible. Every word must count.
  • As you edit the paper ask yourself constantly, “can I make the same point in less space?” and “Do I really have to say this?”
  • When in doubt, leave it out
  • Don’t repeat things. In other words, if you’ve said it once, you don’t have to say it again. Most of all, it uses up extra space and reader’s patience to have to see the same point made over and over again.
  • Using the phrase “In other words” is a sign of trouble. (I admit I do this all the time!) Go back and say it once, right.
  • General points
  • Strive for precision. Read each sentence carefully. Does each sentence say something, and does it mean what it says?
  • Document your work. A fellow graduate student must be able to sit down with your paper and all alone reproduce every number in it from instructions given in the paper, and any print or web appendices.
  • Simple is better. Most students think they have to dress up a paper to look impressive. The exact opposite is true: The less math used, the better. The simpler the estimation technique, the better. Anecdote – iPhone!
  • Don't repeatBe preciseDocument your workSimple is best
  • Writing tips
  • The most important thing in writing is to keep track of what your reader knows and doesn’t know.
  • This brings us back to ourKaplan book -
  • Knowing the audience is the key to any successful technical communicationTailor the communication to meet the needs of that audience
  • ask yourself who are your intended readers?
  • try to consider the knowledge level of the audience
  • Most writers assume far too much. No, we do not have the details of every paper ever written in our heads.
  • Keep in mind what you have explained and what you have not.
  • The reader usually wants to understand your basic point, and won’t start criticizing it before he or she understands it.
  • Thus, I advise writers to first state and explain what you do, and save defending it and comparing it to other approaches until much later.
  • Use active tense. Not: “it is assumed that x = 3”, “data were constructed as follows.” Gee, I wonder who did that assuming and constructing?
  • Search for “is” and “are” in the document to root out every single passive sentence.
  • ANECDOTE – Mr. Freeman, my freshman year writing teacher, only let us use five forms of the verb “to be”
  • Much bad writing comes down to trying to avoid responsibility for what you’re saying.
  • That’s why people resort to passive sentences and use poor organization that puts the literature first and your idea last, and so on.
  • Take a deep breath, and take responsibility for what you’re writing.
  • Audience is kingAssume nothingActive verbsTake responsibility
  • Present tense is usually best. You can say “Fama and French 1993 find that” even though 1993 was a while ago.
  • The same goes for your own paper; describe what you find in Table 5 not what you will find in Table 5.
  • Most importantly, though, keep the tense consistent. Don’t start a paragraph in past tense and finish it in the future.
  • Use the normal sentence structure: subject, verb, object. SVO IS THE WAY TO GO!
  • Not: “The insurance mechanisms that agents utilize to smooth consumption in the face of transitory earnings fluctuations are diverse”
  • Instead: “People use a variety of insurance mechanisms to smooth consumption.”
  • Avoid technical jargon wherever possible.
  • Show it to your mother (if she reads English ;-)
  • Writing should be concrete, not abstract. (Insert concrete examples.)
  • Present tense (be consistent) Subject, verb, objectNo jargonConcrete examples
  • Little writing tips
  • Don’t use adjectives to describe your work: “striking results” “very significant” coefficients, etc. If the work merits adjectives, the world will give them to you.
  • If you must use adjectives, don’t use double adjectives. Results are certainly not “very novel.”
  • Use simple short words not big fancy words. “Use” not “utilize” “Several” not “diverse”
  • Readers value your original idea, your contribution, not your fancy vocabulary. Use only words you KNOW.
  • Don’t start your paper with a cute quotation.
  • ADD KITTY CHAN IMAGE IF TIME
  • Add kitty chan image if time…
  • Add kitty chan image if time…
  • Sorry, Kitty-chan!
  • Minimize adjectivesNo quotes
  • Professor Cochrane’s Conclusion
  • Join the noble profession of writers.
  • Many economists falsely think of themselves as scientists who just “write up” research. We are not; we are primarily writers.
  • Economics and finance papers are essays. Most good economists spend at least 50% of the time they put into any project on writing. For me, it’s more like 80%.
  • Pay attention to the writing in papers you read, and notice the style adopted by authors you admire.
  • I got a lot out of reading William Zinsser’s "On Writing Well."
  • http://www.amazon.co.jp/Writing-Well-30th-Anniversary-Nonfiction/dp/0060891548/ref=sr_1_1?ie=UTF8&s=english-books&qid=1275026598&sr=8-1
  • Strunk and White’s The Elements of Style
  • probably the best-known grammar and style text. Its witty style makes it an actual pleasure to read — very unusual for grammar texts. http://www.amazon.co.jp/gp/product/020530902X/ref=s9_simh_gw_p14_i3?pf_rd_m=AN1VRQENFRJN5&pf_rd_s=center-1&pf_rd_r=0R75NK5K9WR0359H64KF&pf_rd_t=101&pf_rd_p=463376736&pf_rd_i=489986
  • Diana Hacker’s “A Pocket Style Manual”
  • quick-reference-style guide to grammar, punctuation, and mechanics. As a bonus, Hacker includes style guides from Chicago Manual, Modern Language Association (MLA), and American Psychological Association (APA.)http://www.amazon.co.jp/gp/product/0312593244/ref=s9_simh_gw_p14_i2?pf_rd_m=AN1VRQENFRJN5&pf_rd_s=center-1&pf_rd_r=0R75NK5K9WR0359H64KF&pf_rd_t=101&pf_rd_p=463376736&pf_rd_i=489986
  • Most of all
  • Learn to write
  • Unfortunately, there aren’t any shortcuts here. The best way is to first learn how to write (anything).
  • Source -Writing great documentation: Technical styleJacob Kaplan-MossNovember 11, 2009 http://jacobian.org/writing/great-documentation/technical-style
  • There are some important differences between (research papers) and your average prose, but a solid foundation of good written communication skills is the fundamental first step
  • So how do you learn to write (anything) well? There’s only one answer: you’ll learn to write well if you write. A lot.
  • You’ll probably want to balance out all this writing with a healthy dose of reading.
  • Learn to identify the mechanical parts of what makes a piece of writing effective; try to identify what succeeds (and what fails) about everything you read.
  • Watch for how authors accomplish “tone”.
  • Read a number of pieces by the same author; you should be able to identify what makes that person’s writing distinctive.
  • Malcolm Gladwell would be one good choice here: his writing style is quite distinctive, somewhat formulaic, and he’s got dozens of his articles online.
  • Most importantly, Gladwell’s style is one that would work very well for technical writing — he’s got a fun, conversational tone that nonetheless can clearly communicate specific technical topics.
  •  Insert Gladwellimage(s) and book titles
  •  Insert Gladwellimage(s) and book titles
  • It doesn’t matter all that much what you’re writing and reading. Tosa says one million words!
  • Sure, there are different rules for fiction and non-fiction, literary criticism and technical documentation, etcBut you can always find something valuable if you keep your eyes and ears open
  • Hendrix was always listening. No such thing as bad music
  • The point is he made it his own
  • The important aspects don’t change, though: good writing is clear, succinct, and communicates ideas effectively.
  • It’s easy to get caught up in wanting your prose to be perfect from the first words you set down. It doesn’t work that way.
  • While you’re writing, turn off the inner critic and just write.
  • While you’re writing, turn off the inner critic and just write. You can turn the critic back on when you proofread and edit later
  • but the important part is to just
  • Do
  • it
  • Write anythingRead everythingReference style guideshttp://delicious.com/admissions/StyleGuidesNotice toneCreate your own
  • Any questions?
  • http://bit.ly/KapTechKaplan Technical Writing: A Resource for Technical Writers at All Levels By Carrie Hannigan, Diane Martinez, Carrie Wells, Tanya Peterson, Carolyn Stevensonhttp://bit.ly/CochranePhDWriting Tips for Ph.D. Students,John H. Cochrane, Graduate School of Business (Booth),University of Chicagohttp://jacobian.org/writing/great-documentation/technical-styleWriting great documentation: Technical style by Jacob Kaplan-Mosshttp://bit.ly/TechWritingBLOG http://techwritingtodai.blogspot.comVINCE http://twitter.com/TokyoVince
  • William Zinsser — “On Writing Well”Strunk and White — “The Elements of Style”Diana Hacker — “A Pocket Style Manual” Malcolm Gladwell — various
  • Review http://bit.ly/CochranePhDRead pages 19-68 of Kaplan book http://bit.ly/KapTech3Check links http://bit.ly/TechWriting
  • Think of three questions you have related to Kaplan Chapter 3 (http://bit.ly/KapTech3) or technical writing in generalWrite them in EnglishEmail to V@VincePrep.com
  • Good luck. Thank you!
  • Transcript

    • 1. University of Tokyo2010
      Technical Writing
      Vince Ricci
      Links here:
      http://bit.ly/TechWriting
    • 2. Vince Ricci
      Stanford University
      B.A., History
      June 1992
      James W. Lyons Award for Service
      Awarded Public Service Summer Fellowship to write & edit National Guide to Fundraising & Development
    • 3. Vince Ricci
      New York University (NYU)
      M.A., Educational Communication & Technology (ECT)
      December 2000
      Cognitive Science Instructional Design
      Museum exhibit design
      Marketing
    • 4.
      • Writing teacher since 1990
      • 5. Louisiana Distinguished Teacher Award while working at top private school in Southeastern U.S.
      • 6. Secured steady funding by writing winning grant proposals from U.S. Government plus major corporations
      • Admissions counselor since 2002
      • 7. Helped over 400 clients write thousands of essays
      • 8. Admitted to every top school including Harvard, Stanford, Kellogg, Chicago, Wharton, MIT
      • 9. 5 will attend HBS from 2010
    • Today’s Focus
      Kaplan book
      Cochrane article
      References
      Homework
    • 10. Part One
    • 11.
    • 12. Kaplan Technical Writing
      Chapter 1: definitions
      Chapter 2: purpose, audience and context
    • 13. CHAPTER 1
    • 14. What is
      technical writing?
    • 15. Informative writing that involves
      technical
      scientific
      engineering-based
      topics
    • 16. Technical communicators
      write and edit user manuals
      research and write grants and proposals
      deliver presentations
    • 17. Convey complex information
      to a specific audience
    • 18. If audience cannot understand or use information presented, writer has failed
    • 19.
    • 20. Good technical writing is accurate, clear, and concise
    • 21.
    • 22. ACCURACY
    • 23. Inaccurate technical documents can result in very real physical, financial, or environmental repercussions
    • 24. CLARITY
    • 25. If a report does not contain clear information, the reader cannot comprehend the writer's intent or follow instructions
    • 26. CONCISENESS
    • 27. Direct language
      that gets right to the point
      It avoids flowery descriptions that can obscure meaning
    • 28. Something cute
    • 29. Goal-oriented
      Convey information
      No extraneous material
      Find essential information
    • 30. Specific format
      Allows reader to quickly locate everything in organized fashion
    • 31. Beautiful in its simplicity
      Sophisticated content
      conveyed in a clean
      and usable way
    • 32.
    • 33.
    • 34. CHAPTER 2
    • 35. PURPOSE
    • 36. AUDIENCE
    • 37. CONTEXT
    • 38. Consider purpose of document Intended audience and
      Context in which the writer is writing or presenting
    • 39. Purpose
      Audience
      Context
    • 40. To take these 3 things
      into account will directly affect
      the effectiveness
      of the technical document
    • 41. If the audience cannot use,
      apply or understand
      information presented
      then the author has failed
    • 42.
    • 43. Because technical communication has set specific goals and requirements, the technical communicator must have a plan for success
    • 44. PURPOSE
    • 45. Ultimate goal?
    • 46. Designed to be practical
    • 47. Purpose determines
      format or style
    • 48. AUDIENCE
    • 49. Key to any successful
      technical communication
    • 50. Tailor communication
      to meet audience needs
    • 51. Technically savvy or
      composed of lay people?
    • 52. Use different language
      when addressing
      technical expert
      as opposed to an audience
      that has limited knowledge
    • 53. Who are your intended readers?
    • 54. What will audience members do with the information?
    • 55. Consider knowledge level
    • 56. CONTEXT
    • 57. Context determines
      how reader or listener
      will receive
      and interpret
      the message
    • 58. Help writer determine
      what format
      is appropriate
      and how subject
      should be approached
    • 59. Failing to consider context
      may result in message
      being rejected
      particularly if the goal
      is to persuade
    • 60. Your Goals
      Accuracy
      Clarity
      Conciseness
    • 61. Remember
      Purpose
      Audience
      Context
    • 62.
    • 63. Kaplan Technical Writing
      Chapter 1: definitions
      Chapter 2: purpose, audience and context
    • 64. Questions?
    • 65. CHAPTER 3
    • 66. HOMEWORK!
    • 67. Part Two
    • 68. Writing Tips
      for Ph.D. Students
    • 69. John H. Cochrane
      Graduate School of Business
      University of Chicago
    • 70.
    • 71.  Insert image
    • 72. 1. ORGANIZATION
    • 73. Figure out the one central and novel contribution of your paper.
      Write this down
      in one paragraph.
      As with all your writing,
      this must be concrete.
    • 74. Don’t write
      “I analyzed data
      on executive compensation
      and found many
      interesting results.”
    • 75. Explain
      the central results
    • 76. For example, Fama and French 1992 start their abstract with
    • 77. “Two easily measured variables, size and book-to-market equity, combine to capture
      the cross-sectional variation
      in average stock returns associated with market β,
      size, leverage,
      book-to-market equity,
      and earnings-price ratios.”
    • 78. “Two easily measured variables size and
      book-to-market equity…
    • 79. “…combine to capture
      the cross-sectional variation…
    • 80. “…in average stock returns…
    • 81. “…associated with
      market β,
      size,
      leverage,
      book-to-market equity,
      and earnings-price ratios.”
    • 82. “Two easily measured variables, size and book-to-market equity, combine to capture
      the cross-sectional variation
      in average stock returns associated with market β,
      size, leverage,
      book-to-market equity,
      and earnings-price ratios.”
    • 83. Distilling one central contribution
      will take some thought.
    • 84. You will start to realize
      how much you’re going to
      have to throw out.
    • 85. Doing so puts you
      in a much better position
      to focus the paper
      on that one contribution,
      and help readers
      to get it quickly.
    • 86. Your readers
      are busy and impatient.
    • 87. No reader will ever
      read the whole thing
      from start to finish.
    • 88. Readers skim.
      Make it easy
      for them to skim.
    • 89. Most readers want to know
      your basic result.
    • 90. Only a few care
      how it is different from others.
    • 91. Organize the paper in “triangular” or “newspaper” style, not in “joke” or “novel” style.
    • 92. Notice how newspapers start
      with the most important part,
      then fill in background later
      for readers who
      want more details.
    • 93. Main idea
    • 94. What
    • 95. A good joke or a mystery novel has a long windup
      to the final punchline.
    • 96. Put the punchline
      right up front
      and then slowly
      explain the joke.
    • 97. Too often, we never really find out
      what the contribution of the paper is until the last page,
      the last table,
      and the last 5 minutes
    • 98. Main idea
    • 99. What
    • 100. A good paper is not a travelogue of your search process.
      We don’t care how you came
      to figure out the right answer.
    • 101. We don’t care about the hundreds of things you tried
      that did not work.
      Save it for your memoirs.
    • 102. Remember
      Contribution first
      Readers skim
      Triangular style
      Open with punchline
    • 103. Your Abstract
    • 104. Most journals
      allow 100-150 words.
      Obey this limit now.
    • 105. The main function of the abstract is to communicate
      the one central
      and novel contribution
    • 106. You should not mention other literature in the abstract.
    • 107. Like everything else,
      the abstract must be concrete.
    • 108. Say what you find,
      not what you look for.
    • 109. Don’t write
      “data are analyzed,
      theorems are proved,
      discussion is made.”
    • 110. Your Introduction
    • 111. The introduction should start
      with what you do in this paper, the major contribution.
      You must explain
      that contribution
      so that people
      can understand it.
    • 112. Don’t just state your conclusion
      “My results show
      that the pecking-order theory
      is rejected.”
    • 113. Give the fact behind that result. “In a regression of x on y, controlling for z,
      the coefficient is q.”
    • 114. The first sentence is the hardest.
    • 115. “Two easily measured variables, size and book-to-market equity, combine to capture
      the cross-sectional variation
      in average stock returns associated with market β,
      size, leverage,
      book-to-market equity,
      and earnings-price ratios.”
    • 116. Do not start with philosophy “Financial economists
      have long wondered
      if markets are efficient.”
    • 117. Do not start with
      “The finance literature
      has long been interested in x.”
    • 118. Your paper must be interesting
      on its own, and not just because lots of other people
      wasted space
      on the subject.
    • 119. Do not start
      with a long motivation
      of how important the issue
      is to public policy.
    • 120. Start with
      your central contribution.
    • 121. “Two easily measured variables, size and book-to-market equity, combine to capture
      the cross-sectional variation
      in average stock returns associated with market β,
      size, leverage,
      book-to-market equity,
      and earnings-price ratios.”
    • 122. How do you add value?
    • 123. Contribution
      A contribution includes an addition to your field’s overall knowledge
    • 124. Something cute
    • 125. Three pages is a good upper limit for the introduction.
    • 126. Remember
      Abstract - no literature review
      Introduction - first sentence
      Start with contribution
    • 127. Your Literature Review
    • 128. Do not start your introduction
      with a page and a half
      of other literature.
    • 129. You
    • 130. First, your readers are most interested in figuring out
      what you do.
    • 131. They can’t start wondering
      if it’s better than
      what others have done
      until they understand
      what you do.
    • 132. Chicken vs. Egg
    • 133. Chicken vs. Egg
    • 134. Most readers
      do not know the literature.
    • 135. Hard enough to explain
      your paper in simple terms.
      Why do you want to explain everyone else’s too?
    • 136. After you’ve explained
      your contribution,
      then you can write
      a brief literature review.
    • 137. Make it a separate section
    • 138. It will be hard
      for people to understand
      how your paper is different
      from others’ given that they
      don’t understand your paper yet,
      and most of them have not read the other papers.
    • 139. Chicken vs. Egg
    • 140. Chicken vs. Egg
    • 141. Main idea
    • 142. What
    • 143. You
    • 144. Be generous in your citations.
    • 145. You do not have to say
      that everyone else did it all wrong for your approach
      and improvements
      to be interesting.
    • 146. Set your paper off against
      2 or 3 closest current papers, and to give proper credit to people who deserve priority for things
      that might otherwise
      seem new
    • 147. Body of Your Paper
    • 148. Your task now
      is to get to the central result
      as fast as possible.
    • 149. Most papers have
      long motivation
      long literature review
      big complex model
      descriptive statistics
      preliminary results
      side discussions then finally Table 12 of “main estimates”
    • 150. boring 
    • 151. boring 
    • 152. Here’s the rule
      Nothing before the main result
      that reader does not
      need to know
      in order to understand
      the main result.
    • 153. Your Conclusions
    • 154. Do not restate all of your findings.
    • 155. One statement in the abstract, one in the introduction
      and once more in the body of the text should be enough.
    • 156. You can include a short paragraph or two acknowledging limitations, suggesting implications beyond those in the paper.
    • 157. Keep it short
      Do not write your grant application here outlining
      all of your plans
      for future research.
    • 158. Don’t speculate
      Reader wants to know
      your facts
      not your opinions.
    • 159. Remember
      Literature review – meaningless before your contribution
      Body of the paper – all about your main result
      Short conclusion
    • 160. 2. WRITING
    • 161. Keep the paper
      as short as possible.
      Every word must count.
    • 162. As you edit, ask yourself
      “Can I make the same point in less space?” and
      “Do I really have to say this?”
    • 163. Something cute
    • 164. Don’t repeat
      If you’ve said it once,
      you don’t have to say it again.
    • 165. repetition
    • 166. repetition
    • 167. “In other words”
      is a sign of trouble.
      Go back and say it once, right.
    • 168. General points
    • 169. Strive for precision
      Read each sentence carefully. Does each sentence say something, and does it mean what it says?
    • 170. Document your work
      A fellow graduate student must be able to sit down with your paper and reproduce every number in it from instructions given in the paper, and any print or web appendices.
    • 171. Simple is better
      Most students dress up a paper. Is this impressive?
      The less math used, the better. The simpler the estimation technique, the better.
    • 172. Remember
      Don't repeat
      Be precise
      Document your work
      Simple is best
    • 173. Writing tips
    • 174. The most important thing
      in writing
      is to keep track
      of what your reader knows
      and doesn’t know.
    • 175. <AUDIENCE>
    • 176. Key to any successful
      technical communication
    • 177. Who are your intended readers?
    • 178. Consider knowledge level
    • 179. Most students assume
      far too much.
    • 180. assumptions
    • 181. assumptions
    • 182. Keep in mind
      what you have explained
      and what you have not.
    • 183. The reader usually wants to understand your basic point, and won’t start criticizing it before he or she understands it.
    • 184. First state and explain
      what you do
      Save defending it and
      comparing to other approaches
      until much later.
    • 185. Use active tense
      Not passive
      “it is assumed that x = 3”
      “data were constructed
      as follows”
    • 186. Search for “is” and “are” in the document to root out every single passive sentence.
    • 187. to be
    • 188. to be
    • 189. Do not avoid responsibility for what you’re saying.
    • 190. People write passive sentences
      poor organization
      with literature first
      and your idea last
    • 191. Take responsibility
      for what you are writing.
    • 192. Remember
      Audience is king
      Assume nothing
      Active verbs
      Take responsibility
    • 193. Present tense is usually best.
      You can say “Fama and French 1993 find that” even though 1993 was a while ago.
    • 194. Describe what you find in Table 5 not what you will find in Table 5.
    • 195. Keep tense consistent.
      Don’t start a paragraph
      in past tense
      and finish it
      in the future.
    • 196. Use normal sentence structure: subject, verb, object.
    • 197. Not
      “The insurance mechanisms
      that agents utilize
      to smooth consumption
      in the face of
      transitory earnings fluctuations
      are diverse”
    • 198. Instead
      “People use a variety
      of insurance mechanisms
      to smooth consumption.”
    • 199. Avoid technical jargon
      wherever possible.
    • 200. jargon
    • 201. jargon
    • 202. Writing should be concrete,
      not abstract.
      (Insert concrete examples.)
    • 203. Remember
      Present tense (be consistent)
      Subject, verb, object
      No jargon
      Concrete examples
    • 204. Little writing tips
    • 205. Don’t use adjectives
      to describe your work
      “striking results”
      “very significant” coefficients
    • 206. adjectives
    • 207. adjectives
    • 208. If you must use adjectives,
      don’t use double adjectives.
      Results are certainly not
      “very novel.”
    • 209. Use simple short words
      not big fancy words.
      “Use” not “utilize”
      “Several” not “diverse”
    • 210. How do you add value?
    • 211. Don’t start your paper
      with a cute quotation.
    • 212. cute
    • 213. cute
    • 214. cute
    • 215. cute
    • 216. Remember
      Minimize adjectives
      No quotes at opening
    • 217. COCHRANE’S
      CONCLUSION
    • 218. Be a writer!
    • 219. Many (economists) falsely
      think of themselves
      as scientists who
      just “write up” research.
      We are not.
      We are primarily writers.
    • 220. (Research) papers are essays. Most good (economists)
      spend at least 50%
      of any project
      on writing.
      For me, it’s more like 80%.
    • 221. Pay attention to the writing in papers you read.
      Notice the style adopted
      by authors you admire.
    • 222. William Zinsser
      “On Writing Well”
    • 223.
    • 224. Strunk and White
      “The Elements of Style”
    • 225.
    • 226. Diana Hacker
      “A Pocket Style Manual”
    • 227.
    • 228. Most of all
    • 229. Learn to write
    • 230. No shortcuts.
      The best way is to first learn how to write (anything).
    • 231. Source –
      “Writing great documentation: Technical style”
      Jacob Kaplan-Moss
      November 11, 2009 
      http://jacobian.org/writing/great-documentation/technical-style
    • 232. There are some important differences between (research papers) and your average prose, but a solid foundation of good written communication skills is the fundamental first step.
    • 233. So how do you
      learn to write (anything) well? There’s only one answer:
      you’ll learn to write well
      if you write.
      A lot.
    • 234. You’ll probably want to balance out all this writing with a healthy dose of reading.
    • 235. Learn to identify the mechanical parts of what makes a piece of writing effective; try to identify what succeeds (and what fails) about everything you read.
    • 236. Watch for how authors accomplish “tone”.
    • 237. Read a number of pieces by the same author; you should be able to identify what makes that person’s writing distinctive.
    • 238. Malcolm Gladwell would be one good choice: his writing style is quite distinctive, somewhat formulaic, and he’s got dozens of his articles online.
    • 239.
    • 240.
    • 241.
    • 242. It doesn’t matter all that much what you’re writing and reading.
    • 243. Different rules for fiction and non-fiction, literary criticism and technical documentation
    • 244.
    • 245.
    • 246. Good writing is clear, succinct, and communicates ideas effectively.
    • 247. It’s easy to get caught up in wanting your prose
      to be perfect
      from the first words
      you set down.
      It doesn’t work that way.
    • 248. While you’re writing,
      turn off the inner critic
      and just write.
    • 249. You can turn the critic back on when you proofread
      and edit later
    • 250. Just
    • 251. do
    • 252. it
    • 253. Become a Writer
      Write anything
      Read everything
      Reference style guides
      Notice tone
      Create your own
    • 254. Questions?
    • 255. Resources & Links
      http://bit.ly/KapTech
      http://bit.ly/CochranePhD
      http://bit.ly/TechWriting
      http://techwritingtodai.blogspot.com
      http://jacobian.org/writing/great-documentation/technical-style
      http://twitter.com/TokyoVince
    • 256. Resources & Links
      William Zinsser — “On Writing Well”
      Strunk and White — “The Elements of Style”
      Diana Hacker — “A Pocket Style Manual”
      Malcolm Gladwell — various
    • 257. Next Steps
      Review slides http://bit.ly/VT-526
      Print/read http://bit.ly/CochranePhD
      Check links http://bit.ly/TechWriting
      Course page
      http://techwritingtodai.blogspot.com
    • 258. Homework
      Coming soon
      Coming soon
      Coming soon
    • 259. Vince’s Perspective
      Good luck!
      http://techwritingtodai.blogspot.com