WRITING FOR DEVELOPERSSOME RATIONAL TECHNIQUES
WHO AM I?
Technical writer for nearly fifteen years, now working as a frontend engineer (gulp!)
@evangoer || [email protected]
Author of the YUI 3 Cookbook, available in fine stores everywhere!
This talk is about tools and style.
Mostly style.
This is not a grammar lecture.
Ce n'est pas une conférence de grammaire.
OVERVIEW
I. Tools that Don’t Suck
II. English is Hard, Let’s Go Shopping!
III. Separating Out Unhelpful Advice
IV. Clarity: Finding Characters and Actions
V. Emphasis: Topic and Stress
“Any correction of the speech or writing of others will contain at least one grammatical, spelling, or typographical error.”
— McKean’s Law
PART ITOOLS THAT DON’T SUCK
WHAT TO LOOK FOR
FEATURES
Plain text, hackable
Multiple output formats
Rich semantics
Code proximity!!
--server mode
ANTI-FEATURES
Proprietary, binary
HTML-only
Presentational
Siloed
WYSIWYG
Gross, ugly HTML <frame>s (seriously, why?)
PART IIENGLISH IS HARD, LET’S GO SHOPPING!
ENGLISH IS A MÉLANGE
Old English Latin FrenchFearlessness,
Guts… Tenacity,Fortitude…
Bravery,
Mettle, Valor …
“English is a language that lurks in dark alleys, beats up other languages, and rifles through their pockets for spare vocabulary.”
— Author Unknown
“English is the PHP of spoken languages.”
— Me
TYPE I ERRORS: BASIC SYNTAX
English has basic structural rules that we can all agree on, like “Subject – Verb – Object.”
Don’t worry about Type I Errors. You won’t make them.
TYPE II ERRORS: UNEDUCATED USAGE
“I should have knowed that.”
Don’t worry about Type II Errors. You won’t make these errors either, unless you’re still learning English.
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. These aren’t actually errors, and it’s not worth your time trying to please people who think that these errors are real.
At best, worrying about grammar and usage is a form of premature optimization.
WHO IS YOUR AUDIENCE?
DEVELOPERS, DEVELOPERS, DEVELOPERS, DEVELOPERS
WILLIAM SAFIRE
PART III^(UN)?HELPFUL ADVICE
THE WORLD IS FULL OF WRITING ADVICE
“BE CLEAR”
A platitude.
Equivalent to, “Hit the ball squarely.”
I already know that! But I don’t know how to hit the ball squarely.
“OMIT NEEDLESS WORDS”
Another platitude.
And as a bonus, a tautology!
Equivalent to, “Omit words that should be omitted.”
“WRITE SHORT SENTENCES”
Equivalent to, “Write short programs.”
All things being equal, a short sentence is better than a long one. But all things are never equal.
There is nothing wrong with a long sentence if that sentence does its job effectively.
“AVOID ADJECTIVES AND ADVERBS.”
Famous quote from Strunk & White, “Write with nouns and verbs, not with adjectives and adverbs.”
Adjectives + adverbs are ~13% of English prose.1 There is no escape.
[1] http://infomotions.com/blog/2011/02/forays-into-parts-of-speech/
SO HOW DO I WRITE GOOD BETTER?
1. Clarity – cleanup at the local sentence level
2. Cohesion and Emphasis – stringing together sentences effectively
3. Coherence – constructing elegant paragraphs, passages, and ultimately documents
Today we will partly explore (1) and (2).
(3) is Sir Not Appearing in this Presentation.
PART IVCLARITY: FINDING CHARACTERS AND ACTIONS
A nominalization is an abstract noun derived from a verb or adjective.
initialize → initialization
minify → minification
elegant → elegance
Easy win: find and eliminate nominalizations and other flabby abstract nouns.
Makes sentences shorter (yay)
Makes your writing more concrete
Clarifies who or what is acting
USING OUR POWERS FOR EVIL, NOT GOOD
“The Architecture Team’s proposal would provide for individual engineering team certification of the resilience of any new applications that were requested for exemption from core BCP guidelines.”
FIND THE ABSTRACT NOUNS
“The Architecture Team’s proposal would provide for individual engineering team certification of the resilience of any new applications that were requested for exemption from core BCP guidelines.”
CONVERT ABSTRACT NOUNS INTO CONCRETE VERBS AND ADJECTIVES
“The Architecture Team proposes that when individual engineering teams ask us to exempt new applications from core BCP guidelines, the team must certify that the technology is resilient.”
(Still not great, but an improvement)
1. 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 --
ENGLISH PROSE READS CLEARLY WHEN
CHARACTERS AND AGENTS
Singular 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.
In the last sentence of the YUI keynote address, there is a rallying cry for the continuation of the struggle for better apps.
Determination of policy occurs at the vice presidential level.
In the last sentence of the YUI keynote address, Dav Glass rallied his audience to continue the struggle for better apps.
The vice president determines policy.
REVEAL THE MISSING CHARACTERS!
BAD NOMINALIZATIONS: EMPTY VERBS I
If the nominalization follows an empty verb, then change the nominalization to a verb that can replace the 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
BAD NOMINALIZATIONS: EMPTY VERBS II
If the nominalization is the subject of an empty verb, then change to a verb and find a new subject.
“Our discussion concerned improving YUI Attribute performance.”
“We discussed improving YUI Attribute performance.”
FIXED Subject Verb Object
VARIABLE discussion concerned performance
VARIABLE we discussed performance
BAD NOMINALIZATIONS: “THERE IS”
If the nominalization follows a “There is,” then change 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 Object
VARIABLE degradation of was hardware
VARIABLE humidity degraded hardware
GOOD NOMINALIZATIONS
Abstract nouns aren’t 100% evil. They exist in the language 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.”
PART VEMPHASIS: TOPIC AND STRESS
TOPIC
FIXED Subject Verb Object
VARIABLE Characters Action --
FIXED Topic Stress
VARIABLE ?? ??
The topic is the “psychological subject.” What is this sentence actually about?
Readers expect the topic of the sentence to correspond with the grammatical subject.
STRESS
When reading English sentences, your voice naturally rises and falls at the end. Stress.
Known information should be at the beginning; new information should be at the end, to be stressed.
FIXED Subject Verb Object
VARIABLE Characters Action --
FIXED Topic Stress
VARIABLE Old Information New Information
… which exceeded even our most pessimistic forecasts. The failure of management to halt rising CapEx costs lies at the heart of the problem.
… which exceeded even our most pessimistic forecasts. At the heart of the problem lies management’s failure to halt rising CapEx costs.
MOVE OLD INFO TO THE BEGINNING
No one can explain how magnets work in a few words.
No one can explain in a few words how magnets work.
STRESS NEW INFO AT THE END
Creating YUI synthetic events is another way to support mobile devices. Synthetic events can …
Another way to support mobile devices is to create YUI synthetic events. Synthetic events can …
STRESS NEW INFO AT THE END, REDUX
… which leads to UI inconsistency on tablets and phones. Frontend engineers familiar with the problems raised by mobile browser fragmentation have confirmed these observations.
… which leads to UI inconsistency on tablets and phones. These observations have been confirmed by frontend engineers familiar with the problems raised by mobile browser fragmentation.
USING PASSIVES FOR GOOD, NOT EVIL
SUMMARYTL;DR – HOW TO WRITE MORE BETTER
1. Don’t worry about what William Safire thinks.
2. Make sure your subjects correspond to characters and your verbs to actions.
“Determination of policy occurs at the vice presidential level.”
vs.
“The vice president determines policy.”
3. Determine the topic of your sentence and make it correspond with the grammatical subject.
“The ball was thrown by Jane.”
vs.
“Jane threw the ball.”
4. To stress new information, move it closer to the end of a sentence.
“No one can explain how magnets work in a few words.”
vs.
“No one can explain in a few words how magnets work.”
5. “Any correction of the speech or writing of others will contain at least one grammatical, spelling, or typographical error.”
Remember McKean’s Law. Humility. Empathy.
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 2
011 by Adria Richards
• City Island Little League ASG 105 by Edwin Martinez
• zen garden by whatnot• My Jedi Book by maxxum_sky
QUESTIONS?