Technical Writing 101

Elizabeth Naramore Dutch PHP Conference June, 2010

ATTENTION.

THERE IS NO CODE HERE.

THIS IS A SOFT SKILLS TALK.

THIS IS A SOFT SKILLS TALK.

(It's not just fluff, but will make you a stronger, more well-rounded developer.) 5

This talk will:

Help you with the writing process Help you improve your own writing Point you to references for the future

This talk pertains to:

Blog posts Articles Technical books Documentation (end-user, dev)

Why do we write?
Money Fame To improve our own knowledge To help other people

Why do we write?
Money (meh.) Fame (meh.) To improve our own knowledge To help other people

You are the only one that can share what you know.
10

A lot of this out there.

(Let's deflate it.)

11

READY?

12

An idea.

13

No ideas?

14

Where do we get ideas?

Problems you've solved (how-to)

15

Where do we get ideas?

Problems you've solved (how-to) People you've met (interview)

16

Where do we get ideas?

Problems you've solved (how-to) People you've met (interview) New things you've tried (opinion)

17

Where do we get ideas?

Problems you've solved (how-to) People you've met (interview) New things you've tried (opinion) Research you've done (news)

18

1. PRE-WRITE.

19

Coredump.

20

Use cubing.

21

Side 1: Describe.

22

Side 2: Compare.

23

Side 3: Associate.

24

Side 4: Analyze.

25

Side 5: Apply.

26

Side 6: Argue.

27

Sort and outline.

28

Plug holes with research.

29

2. WRITE.

30

3. EDIT. (Make it not suck.)

31

First, the easy-ish stuff.

32

Respect the rules of the language.

33

Check your facts.

34

I believe more in the scissors than I do in the pencil. - Truman Capote

35

Choose words wisely.

The difference between the right word and the almost right word is the difference between lightning and the lightning bug. - Mark Twain

36

Simplify.

37

Simplify.
The specimen of the canine species consumed the edible substance belonging to him.

38

Simplify.
The specimen of the canine species consumed the edible substance belonging to him. versus The dog ate his food.
39

Keep paragraphs small (but not too small).

Good estimate is 5-6 sentences
40

Second, the not so easy-ish stuff.

41

Clear logic. Clear writing.

42

Keep the flow going.

43

Don't dilute your message.

44

Think like your reader.

Empathy: Identification with and understanding of another's situation, feelings, and motives.

45

Let's do a cheesy exercise.

46

47

48

49

End result:

Right?
50

If you don't tell me, I don't know.

51

STOP. (We're not quite done yet.)

52

Read it aloud. Does it flow?

53

Elicit a second opinion.

(Some things only seem like a good idea.)

54

More stuff to remember.

55

Bad writing is easy. Bad writing makes reading hard.

56

Good writing is hard. Good writing makes reading easy.

57

Practice makes perfect.

58

Find your own style.

(Hopefully, it's somewhere between these two.)

59

Don't lose the human element.

Why's (Poignant) Guide to Ruby

60

Writing is not a contest or a race.

61

You are the only one that can share what you know.
62

Idea. Pre-write. Write. Edit & De-suckify. Repeat.

63

RECAP

This looks familiar.

64

RECAP Software Requirements. Planning & Testing. Coding. Refactoring. Repeat.

65

Need references for later?

Elements of Style by Strunk & White Pocket Book of Grammar for Engineers and Scientists NYT Manual of Style and Usage Merriam Webster's Punctuation and Style Dictionary of Misspelled Words

66

Want to contact me?

http://naramore.net/blog @ElizabethN elizabeth@naramore.net Freenode IRC: ElizabethN
THANKS! several images were used with permission from: - The awesome folks at Cheezburger Network (http://cheezburger.com/sites) - Matt Ballard (http://realitysideb.com)

67