WRITING FOR DEVELOPERSSOME RATIONAL TECHNIQUES

WHO AM I?

Technical writer for nearly fifteen years, now working as a frontend engineer (gulp!)

@evangoer || evan@goer.org

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?