WRITING FORDEVELOPERSSOME RATIONAL TECHNIQUES
WHO AM I?Technical writer for nearlyfifteen years, now workingas a frontend engineer(gulp!)@evangoer || evan@goer.orgAutho...
This talk is about tools and style.Mostly style.
This is not a grammar lecture.Ce nest pas une conférence degrammaire.
OVERVIEWI.     Tools that Don’t SuckII.    English is Hard, Let’s Go Shopping!III.   Separating Out Unhelpful AdviceIV.   ...
―Any correction of thespeech or writing of otherswill contain at least onegrammatical, spelling, ortypographical error.‖  ...
PART ITOOLS THAT DON’T SUCK
WHAT TO LOOK FORFEATURES                  ANTI-FEATURESPlain text, hackable      Proprietary, binaryMultiple output format...
PART IIENGLISH IS HARD, LET’S GO SHOPPING!
ENGLISH IS A MÉLANGEOld English     Latin        FrenchFearlessness,   Tenacity,    Bravery,Guts…           Fortitude…   M...
―English is a language thatlurks in dark alleys, beatsup other languages, andrifles through their pocketsfor spare vocabul...
―English is the PHP ofspoken languages.‖                     — Me
TYPE I ERRORS: BASIC SYNTAXEnglish has basic structural rules that wecan all agree on, like ―Subject – Verb –Object.‖Don’t...
TYPE II ERRORS: UNEDUCATED USAGE―I should have knowed that.‖Don’t worry about Type II Errors. You won’tmake these errors e...
TYPE III ERRORS: NITPICKERY―To boldly go where no one has gone...‖―To go boldly where no one has gone…‖Don’t worry about T...
At best, worrying about grammarand usage is a form of prematureoptimization.
WHO IS YOUR AUDIENCE?DEVELOPERS, DEVELOPERS,                          WILLIAM SAFIREDEVELOPERS, DEVELOPERS
PART III^(UN)?HELPFUL ADVICE
THE WORLD IS FULL OF WRITING ADVICE
“BE CLEAR”A platitude.Equivalent to, ―Hitthe ball squarely.‖I already knowthat! But I don’tknow how to hitthe ball squarely.
“OMIT NEEDLESSWORDS”Another platitude.And as a bonus,a tautology!Equivalent to,―Omit words thatshould beomitted.‖
“WRITE SHORTSENTENCES”Equivalent to, ―Writeshort programs.‖All things being equal,a short sentence isbetter than a long on...
“AVOIDADJECTIVES ANDADVERBS.”Famous quote fromStrunk & White,“Write with nounsand verbs, not withadjectives andadverbs.”Ad...
SO HOW DO I WRITE GOOD BETTER?1. Clarity – cleanup at the local sentence level2. Cohesion and Emphasis – stringing togethe...
PART IVCLARITY: FINDING CHARACTERS AND ACTIONS
A nominalization is an abstractnoun derived from a verb oradjective.initialize → initializationminify → minificationelegan...
Easy win: find and eliminatenominalizations and other flabbyabstract nouns.Makes sentences shorter (yay)Makes your writing...
USING OUR POWERS FOR EVIL, NOT GOOD―The Architecture Team’s proposalwould provide for individualengineering team certifica...
FIND THE ABSTRACT NOUNS―The Architecture Team’s proposalwould provide for individualengineering team certification of ther...
CONVERT ABSTRACT NOUNS INTO CONCRETEVERBS AND ADJECTIVES―The Architecture Team proposes thatwhen individual engineering te...
ENGLISH PROSE READS CLEARLY WHEN1. The subjects of the sentences name the   cast of characters.2. The verbs for those subj...
CHARACTERS AND AGENTSSingular Agents   Tilo Mitra explored YUI behavior in Windows 8.Collective Agents   YUI engineers t...
REVEAL THE MISSING CHARACTERS!In the last sentence of the    In the last sentence of theYUI keynote address, there     YUI...
BAD NOMINALIZATIONS: EMPTY VERBS IIf the nominalization follows an empty verb, thenchange the nominalization to a verb tha...
BAD NOMINALIZATIONS: EMPTY VERBS IIIf the nominalization is the subject of an emptyverb, then change to a verb and find a ...
BAD NOMINALIZATIONS: “THERE IS”If the nominalization follows a ―There is,‖ thenchange to a verb and find a better subject....
GOOD NOMINALIZATIONSAbstract nouns aren’t 100% evil. They exist in thelanguage for a reason. Use them to refer to:A wordy ...
PART VEMPHASIS: TOPIC AND STRESS
TOPICThe topic is the ―psychological subject.‖ What isthis sentence actually about?Readers expect the topic of the sentenc...
STRESSWhen reading English sentences, your voicenaturally rises and falls at the end. Stress.Known information should be a...
MOVE OLD INFO TO THE BEGINNING… which exceeded even        … which exceeded evenour most pessimistic         our most pess...
STRESS NEW INFO AT THE ENDNo one can explain    No one can explain in ahow magnets work in   few words howa few words.    ...
STRESS NEW INFO AT THE END, REDUXCreating YUI synthetic   Another way to supportevents is another way    mobile devices is...
USING PASSIVES FOR GOOD, NOT EVIL… which leads to UI           … which leads to UIinconsistency on tablets      inconsiste...
SUMMARYTL;DR – HOW TO WRITE MORE BETTER
1. Don’t worry about whatWilliam Safire thinks.
2. Make sure your subjectscorrespond to charactersand your verbs to actions.―Determination of policy occursat the vice pre...
3. Determine the topic of yoursentence and make itcorrespond with thegrammatical subject.―The ball was thrown by Jane.‖   ...
4. To stress new information,move it closer to the end of asentence.―No one can explain howmagnets work in a few words.‖  ...
5. ―Any correction of thespeech or writing of others willcontain at least onegrammatical, spelling, ortypographical error....
FLICKR PHOTO CREDITS: CC-BY• Viking Statue by Frank Douwes• Statue of the Roman Emperor Trajan by Bruno  Girin• L’Arc de T...
QUESTIONS?
Writing for Developers: Some Rational Techniques (YUIConf 2012)
Upcoming SlideShare
Loading in …5
×

Writing for Developers: Some Rational Techniques (YUIConf 2012)

1,343 views

Published on

So you've written a shiny new module or library... now you've got to explain how to use it. In this presentation we'll talk about *how* to be clear, using logical principles for breaking down and organizing prose at the micro level. Above all, we'll talk about how to avoid bad advice and focus on what matters. This is the stuff your college writing instructors should have taught you, but probably didn't.

Published in: Technology
  • Be the first to comment

Writing for Developers: Some Rational Techniques (YUIConf 2012)

  1. 1. WRITING FORDEVELOPERSSOME RATIONAL TECHNIQUES
  2. 2. WHO AM I?Technical writer for nearlyfifteen years, now workingas a frontend engineer(gulp!)@evangoer || evan@goer.orgAuthor of the YUI 3Cookbook, available in finestores everywhere!
  3. 3. This talk is about tools and style.Mostly style.
  4. 4. This is not a grammar lecture.Ce nest pas une conférence degrammaire.
  5. 5. OVERVIEWI. Tools that Don’t SuckII. English is Hard, Let’s Go Shopping!III. Separating Out Unhelpful AdviceIV. Clarity: Finding Characters and ActionsV. Emphasis: Topic and Stress
  6. 6. ―Any correction of thespeech or writing of otherswill contain at least onegrammatical, spelling, ortypographical error.‖ — McKean’s Law
  7. 7. PART ITOOLS THAT DON’T SUCK
  8. 8. WHAT TO LOOK FORFEATURES ANTI-FEATURESPlain text, hackable Proprietary, binaryMultiple output formats HTML-onlyRich semantics PresentationalCode proximity!! Siloed--server mode WYSIWYG Gross, ugly HTML <frame>s (seriously, why?)
  9. 9. PART IIENGLISH IS HARD, LET’S GO SHOPPING!
  10. 10. ENGLISH IS A MÉLANGEOld English Latin FrenchFearlessness, Tenacity, Bravery,Guts… Fortitude… Mettle, Valor …
  11. 11. ―English is a language thatlurks in dark alleys, beatsup other languages, andrifles through their pocketsfor spare vocabulary.‖ — Author Unknown
  12. 12. ―English is the PHP ofspoken languages.‖ — Me
  13. 13. TYPE I ERRORS: BASIC SYNTAXEnglish has basic structural rules that wecan all agree on, like ―Subject – Verb –Object.‖Don’t worry about Type I Errors. You won’tmake them.
  14. 14. TYPE II ERRORS: UNEDUCATED USAGE―I should have knowed that.‖Don’t worry about Type II Errors. You won’tmake these errors either, unless you’restill learning English.
  15. 15. TYPE III ERRORS: NITPICKERY―To boldly go where no one has gone...‖―To go boldly where no one has gone…‖Don’t worry about Type III Errors. Thesearen’t actually errors, and it’s not worthyour time trying to please people who thinkthat these errors are real.
  16. 16. At best, worrying about grammarand usage is a form of prematureoptimization.
  17. 17. WHO IS YOUR AUDIENCE?DEVELOPERS, DEVELOPERS, WILLIAM SAFIREDEVELOPERS, DEVELOPERS
  18. 18. PART III^(UN)?HELPFUL ADVICE
  19. 19. THE WORLD IS FULL OF WRITING ADVICE
  20. 20. “BE CLEAR”A platitude.Equivalent to, ―Hitthe ball squarely.‖I already knowthat! But I don’tknow how to hitthe ball squarely.
  21. 21. “OMIT NEEDLESSWORDS”Another platitude.And as a bonus,a tautology!Equivalent to,―Omit words thatshould beomitted.‖
  22. 22. “WRITE SHORTSENTENCES”Equivalent to, ―Writeshort programs.‖All things being equal,a short sentence isbetter than a long one.But all things arenever equal.There is nothingwrong with a longsentence if thatsentence does its jobeffectively.
  23. 23. “AVOIDADJECTIVES ANDADVERBS.”Famous quote fromStrunk & White,“Write with nounsand verbs, not withadjectives andadverbs.”Adjectives + adverbsare ~13% of Englishprose.1 There is noescape.[1]http://infomotions.com/blog/2011/02/forays-into-parts-of-speech/
  24. 24. SO HOW DO I WRITE GOOD BETTER?1. Clarity – cleanup at the local sentence level2. Cohesion and Emphasis – stringing together sentences effectively3. Coherence – constructing elegant paragraphs, passages, and ultimately documentsToday we will partly explore (1) and (2).(3) is Sir Not Appearing in this Presentation.
  25. 25. PART IVCLARITY: FINDING CHARACTERS AND ACTIONS
  26. 26. A nominalization is an abstractnoun derived from a verb oradjective.initialize → initializationminify → minificationelegant → elegance
  27. 27. Easy win: find and eliminatenominalizations and other flabbyabstract nouns.Makes sentences shorter (yay)Makes your writing more concreteClarifies who or what is acting
  28. 28. USING OUR POWERS FOR EVIL, NOT GOOD―The Architecture Team’s proposalwould provide for individualengineering team certification of theresilience of any new applications thatwere requested for exemption fromcore BCP guidelines.‖
  29. 29. FIND THE ABSTRACT NOUNS―The Architecture Team’s proposalwould provide for individualengineering team certification of theresilience of any new applications thatwere requested for exemption fromcore BCP guidelines.‖
  30. 30. CONVERT ABSTRACT NOUNS INTO CONCRETEVERBS AND ADJECTIVES―The Architecture Team proposes thatwhen individual engineering teams askus to exempt new applications fromcore BCP guidelines, the team mustcertify that the technology isresilient.‖(Still not great, but an improvement)
  31. 31. ENGLISH PROSE READS CLEARLY WHEN1. The subjects of the sentences name the cast of characters.2. The verbs for those subjects name the crucial actions of those characters. FIXED Subject Verb Object VARIABLE Characters Action --
  32. 32. CHARACTERS AND AGENTSSingular Agents  Tilo Mitra explored YUI behavior in Windows 8.Collective Agents  YUI engineers tested YUI on Windows 8.Instrumental Agents  Studies of YUI performance reveal these figures.  When we study YUI’s performance, we find these figures.
  33. 33. REVEAL THE MISSING CHARACTERS!In the last sentence of the In the last sentence of theYUI keynote address, there YUI keynote address, Davis a rallying cry for the Glass rallied his audience tocontinuation of the struggle continue the struggle forfor better apps. better apps.Determination of policy The vice presidentoccurs at the vice determines policy.presidential level.
  34. 34. BAD NOMINALIZATIONS: EMPTY VERBS IIf the nominalization follows an empty verb, thenchange the nominalization to a verb that can replacethe empty verb  ―The team has an expectation that it will ship on the deadline.‖  ―The team expects to ship on the deadline.‖ FIXED Subject Verb Object VARIABLE The team has expectation VARIABLE The team expects deadline
  35. 35. BAD NOMINALIZATIONS: EMPTY VERBS IIIf the nominalization is the subject of an emptyverb, then change to a verb and find a newsubject.  ―Our discussion concerned improving YUI Attribute performance.‖  ―We discussed improving YUI Attribute performance.‖FIXED Subject Verb ObjectVARIABLE discussion concerned performanceVARIABLE we discussed performance
  36. 36. BAD NOMINALIZATIONS: “THERE IS”If the nominalization follows a ―There is,‖ thenchange to a verb and find a better subject.  ―There was considerable degradation of the hardware due to the high humidity.‖  ―The high humidity considerably degraded the hardware.‖FIXED Subject Verb ObjectVARIABLE degradation of was hardwareVARIABLE humidity degraded hardware
  37. 37. GOOD NOMINALIZATIONSAbstract nouns aren’t 100% evil. They exist in thelanguage for a reason. Use them to refer to:A wordy noun or concept in the previous sentence.  ―This decision can lead to costly consequences.‖An often-repeated concept / well-known jargon:  ―Separation of concerns.‖  ―Taxation without representation.‖
  38. 38. PART VEMPHASIS: TOPIC AND STRESS
  39. 39. TOPICThe topic is the ―psychological subject.‖ What isthis sentence actually about?Readers expect the topic of the sentence tocorrespond with the grammatical subject. FIXED Topic Stress VARIABLE ?? ?? FIXED Subject Verb Object VARIABLE Characters Action --
  40. 40. STRESSWhen reading English sentences, your voicenaturally rises and falls at the end. Stress.Known information should be at the beginning; newinformation should be at the end, to be stressed. FIXED Topic Stress VARIABLE Old Information New Information FIXED Subject Verb Object VARIABLE Characters Action --
  41. 41. MOVE OLD INFO TO THE BEGINNING… which exceeded even … which exceeded evenour most pessimistic our most pessimisticforecasts. The failure of forecasts. At the heart ofmanagement to halt the problem liesrising CapEx costs lies at management’s failure tothe heart of the halt rising CapEx costs.problem.
  42. 42. STRESS NEW INFO AT THE ENDNo one can explain No one can explain in ahow magnets work in few words howa few words. magnets work.
  43. 43. STRESS NEW INFO AT THE END, REDUXCreating YUI synthetic Another way to supportevents is another way mobile devices is toto support mobile create YUI syntheticdevices. Synthetic events. Syntheticevents can … events can …
  44. 44. USING PASSIVES FOR GOOD, NOT EVIL… which leads to UI … which leads to UIinconsistency on tablets inconsistency on tabletsand phones. Frontend and phones. Theseengineers familiar with the observations have beenproblems raised by mobile confirmed by frontendbrowser fragmentation engineers familiar with thehave confirmed these problems raised by mobileobservations. browser fragmentation.
  45. 45. SUMMARYTL;DR – HOW TO WRITE MORE BETTER
  46. 46. 1. Don’t worry about whatWilliam Safire thinks.
  47. 47. 2. Make sure your subjectscorrespond to charactersand your verbs to actions.―Determination of policy occursat the vice presidential level.‖ vs.―The vice presidentdetermines policy.‖
  48. 48. 3. Determine the topic of yoursentence and make itcorrespond with thegrammatical subject.―The ball was thrown by Jane.‖ vs.―Jane threw the ball.‖
  49. 49. 4. To stress new information,move it closer to the end of asentence.―No one can explain howmagnets work in a few words.‖ vs.―No one can explain in a fewwords how magnets work.‖
  50. 50. 5. ―Any correction of thespeech or writing of others willcontain at least onegrammatical, spelling, ortypographical error.‖Remember McKean’s Law.Humility. Empathy.
  51. 51. FLICKR PHOTO CREDITS: CC-BY• Viking Statue by Frank Douwes• Statue of the Roman Emperor Trajan by Bruno Girin• L’Arc de Triomphe by Oliver Mallich• Women 2.0 Startup Weekend San Francisco 2011 by Adria Richards• City Island Little League ASG 105 by Edwin Martinez• zen garden by whatnot• My Jedi Book by maxxum_sky
  52. 52. QUESTIONS?

×