Technical Writing 101 Elizabeth Naramore Dutch PHP Conference - PowerPoint PPT Presentation

Technical Writing 101 Elizabeth Naramore Dutch PHP Conference June, 2010 1

ATTENTION. 2

THERE IS NO CODE HERE. 3

THIS IS A SOFT SKILLS TALK. 4

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 6

This talk pertains to: Blog posts Articles Technical books Documentation (end-user, dev) 7

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

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

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

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

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