DinosaurJS: Technical Writing for Developers Workshop

Slide 1

Slide 1 text

FOR DEVELOPERS TECHNICAL WRITING Meeka Gayhart @ccanduc

Slide 2

Slide 2 text

BEFORE WE START White/Silver: I would prefer not to be ‘called on’ during the workshop Blue/Teal: I would prefer not to be asked to read out loud Red/Gold: I will be able to focus better today if I can be on my laptop/phone during this workshop don’t judge me Everything Else: I just like beads GET COMFORTABLE, GRAB BEADS, GRAB PAPER, MEET PEOPLE, CHECK EMAIL, WHATEVER WORKS!

Slide 3

Slide 3 text

WHAT

Slide 4

Slide 4 text

Technical writers […] prepare instruction manuals, how-to guides, journal articles, and other supporting documents to communicate complex and technical information more easily. They also develop, gather, and disseminate technical information through an organization’s communications channels.

Slide 5

Slide 5 text

From Writing that Works by Dr. Steven M. Gerson

Slide 6

Slide 6 text

VERY GOOD ALSO VERY GOOD

Slide 7

Slide 7 text

A GIFT FROM STEVE

Slide 8

Slide 8 text

WHY

Slide 9

Slide 9 text

No content

Slide 10

Slide 10 text

IT BEGINS…

Slide 11

Slide 11 text

NEWS.COM.AU INVESTIGATES…

Slide 12

Slide 12 text

THE PLOT THICKENS

Slide 13

Slide 13 text

GRAPHIC PICTURES

Slide 14

Slide 14 text

No content

Slide 15

Slide 15 text

EXERCISE: WRITE WHAT YOU KNOW

Slide 16

Slide 16 text

▸ Grab a few sheets of paper ▸ Pick a product you work on (professionally or for fun) ▸ In the top right corner, write you initials and a favorite word RRGDingus ▸ Write (legibly) a one to two sentence description of the product I work on the Splice Sounds Library This product lets you purchase royalty free samples. We integrate directly with Ableton, Garageband, etc so you can drag and drop samples and loops you’ve purchased directly into your DAW. ▸ Write the ﬁrst four steps someone would take to start using the product 1. Sign up for a trial account 2. Download the desktop application 3. Browse sounds on the app or website 4. Download sounds to be automatically downloaded by the desktop app WHAT YOU’LL DO

Slide 17

Slide 17 text

HOLD ON TO THAT PAPER, OKAY?

Slide 18

Slide 18 text

THE IMPORTANCE OF BEING ERNEST

Slide 19

Slide 19 text

WHAT HAPPENS TO THE BRAIN WHEN WE READ? Stanislas Dehaene: Reading in the Brain: The New Science of How We Read ▸ Only the center of the retina, called the fovea, has a ﬁne enough resolution to allow for the recognition of small print. Each of them[words] is then split up into myriad fragments by retinal neurons and must be put back together before it can be recognized. ▸ Two major parallel processing routes eventually come into play: the phonological route, which converts letters into speech sounds, and the lexical route, which gives access to a mental dictionary of word meanings. ▸ Your eyes scan the page in short spasmodic movements. Four or ﬁve times per second, your gaze stops just long enough to recognize one or two words.

Slide 20

Slide 20 text

Merlin Mann Email is a funny thing. People hand you these single little messages that are no heavier than a river pebble. But it doesn't take long until you have acquired a pile of pebbles that's taller than you and heavier than you could ever hope to move, even if you wanted to do it over a few dozen trips. But for the person who took the time to hand you their pebble, it seems outrageous that you can't handle that one tiny thing.

Slide 21

Slide 21 text

OH NO, MY ROCKS

Slide 22

Slide 22 text

WRITTEN COMMUNICATION IS INHERENTLY ASSIGNING SOMEONE ELSE A CHORE

Slide 23

Slide 23 text

“WE TAKE OUR CUSTOMERS’ SAFETY SERIOUSLY AND RECOMMEND ALL CONSUMERS SHOULD ALWAYS READ AND FOLLOW THE INSTRUCTIONS PROVIDED” - NUTRIBULLET

Slide 24

Slide 24 text

EXERCISE: TELEPHONE

Slide 25

Slide 25 text

▸ Pass your product description to the person on your right HJWpalindrome Random summary statement about a product 1. Step one 2. Step two 3. Overly complex step three 4. Step ﬁve, for some reason LET’S DO THIS TOGETHER ▸ Get a new piece of paper HJWpalindrome ▸ Copy the “uuid” in the top right ▸ Read the paper you received ▸ Pass the old paper up to the front, keep your copy ▸ You have three minutes to write as much as you remember Uh this company makes zippers I think?

Slide 26

Slide 26 text

HOW YA FEELING?

Slide 27

Slide 27 text

No content

Slide 28

Slide 28 text

▸ Pass your product description to the person on your right HJWpalindrome Random summary statement about a product 1. Step one 2. Step two 3. Overly complex step three 4. Step ﬁve, for some reason AND AGAIN! ▸ Get a new piece of paper HJWpalindrome ▸ Copy the “uuid” in the top right ▸ Read the paper you received ▸ Pass the old paper up to the front, keep your copy ▸ You have three minutes to write as much as you remember Uh this company makes zippers I think?

Slide 29

Slide 29 text

PASS THE PAPERS UP

Slide 30

Slide 30 text

WHAT IS YOUR GOAL HERE?

Slide 31

Slide 31 text

SOME FANCY TERMS CONTEXT FOR WRITING: THE RHETORICAL SITUATION Bitzer, Lloyd. "The Rhetorical Situation." Philosophy and Rhetoric (1968), Audience Exigence Constraints

Slide 32

Slide 32 text

SOME FANCY TERMS AIMS OF DISCOURSE ‣ Literary Discourse ‣ Expressive Discourse ‣ Persuasive Discourse ‣ Referential Discourse Your self published autobiography Possibly also your autobiography A proposal, a cover letter A README, an instruction manual Technical Writing for Software Engineers - Linda Levine Linda H. Peasant Susan B Dunkle

Slide 33

Slide 33 text

No content

Slide 34

Slide 34 text

THOSE DESCRIPTIONS LET’S REVIEW

Slide 35

Slide 35 text

TECHNICAL WRITING BEST PRACTICES

Slide 36

Slide 36 text

SOME FANCY TERMS COMMUNICATION TRIANGLE Technical Writing for Software Engineers - Linda Levine Linda H. Peasant Susan B Dunkle

Slide 37

Slide 37 text

DON’T ASSUME A COMMON WORLD OR SIGNAL

Slide 38

Slide 38 text

EXERCISE: TRANSLATION

Slide 39

Slide 39 text

WWW.TRANSLATIONPARTY.COM Review the telephone versions of your descriptions Pick out a line or two from your original that didn’t make it to the telephone copies Run those lines through translation party Try running a few random sentences

Slide 40

Slide 40 text

No content

Slide 41

Slide 41 text

WHAT KINDS OF THINGS THREW IT OFF?

Slide 42

Slide 42 text

CONCERNS JARGON & DOMAIN SPECIFIC KNOWLEDGE Deﬁned: “A vocabulary particular to a place of work” Depends on: Audience familiarity This product lets you purchase royalty free samples. We integrate directly with Ableton, Garageband, etc so you can drag and drop samples and loops you’ve purchased directly into your DAW. 1. Sign up for a trial account

Slide 43

Slide 43 text

No content

Slide 44

Slide 44 text

No content

Slide 45

Slide 45 text

No content

Slide 46

Slide 46 text

CONCERNS WAYS TO IMPROVE Put your first abbreviation usage in parenthesis Consider replacing ….drag and drop [..] directly into your digital audio workspace (DAW) ….drag and drop [..] directly into your recording software Put the first instance in italics and define … lets you purchase royalty free samples (individual sounds and loops, that can be used without worrying about copyrights).

Slide 47

Slide 47 text

CONCERNS WAYS TO IMPROVE Give Reference Links Sign up for a trial account at Splice.com A great way to understand the product is to play with our Beatmaker tool (https://splice.com/sounds/beatmaker)

Slide 48

Slide 48 text

IT DEPENDS ON YOUR AUDIENCE Who are you selling your product to? Who do you have a responsibility towards?

Slide 49

Slide 49 text

CONCERNS UNNEEDED WORDS Depends on: Context This product lets you purchase royalty free samples. We integrate directly with Ableton, Garageband, etc so you can drag and drop samples and loops you’ve purchased directly into your DAW. YUCK

Slide 50

Slide 50 text

UNNEEDED WORDS BONUS WORDS! From Sentence Structure of Technical Writing: Nicole Kelley

Slide 51

Slide 51 text

UNNEEDED WORDS NEEDLESS COMPLEXITY From Sentence Structure of Technical Writing: Nicole Kelley

Slide 52

Slide 52 text

UNNEEDED WORDS WEAK VOICE From Sentence Structure of Technical Writing: Nicole Kelley

Slide 53

Slide 53 text

CONCERNS WAYS TO IMPROVE Is there a ‘less fancy word’? Read out loud This product lets you purchase buy royalty free samples. We integrate directly with Ableton, Garageband, etc so you can drag and drop samples and loops you’ve purchased directly into your DAW. DOES THIS EVEN MAKE SENSE? Am I repeating myself? We integrate directly with … Our desktop application integrates with most major recording software (Ableton, Garageband, etc), allowing instant access to new samples as you work.

Slide 54

Slide 54 text

IT DEPENDS ON THE CONTEXT + Literary and Expressive contexts - unless you’re Hemmingway Is it important to you that most readers to get to the end? - Referential contexts +/- Persuasive contexts

Slide 55

Slide 55 text

DO WE HAVE SUPER INTENSE RULES LIKE THIS? https://chris.beams.io/posts/git-commit

Slide 56

Slide 56 text

CONCERNS BEING FUNNY/COLLOQUIALISMS Depends on: Audience, Context

Slide 57

Slide 57 text

JOKES CAN BE HUMANIZING BUT THEY DEPEND ON SHARED CONTEXT LANGUAGE LIFE EXPERIENCE INFORMALITY ADDS COGNITIVE LOAD LEAVE IT OUT OF THE CRITICAL TO UNDERSTAND BITS

Slide 58

Slide 58 text

AND YOU MIGHT NOT BE FUNNY TO EVERYONE

Slide 59

Slide 59 text

BEING “FUNNY” ALEX

Slide 60

Slide 60 text

No content

Slide 61

Slide 61 text

PROGRAMATIC CHANGES

Slide 62

Slide 62 text

THOUGHTS FROM 1986 ▸ considers: “top-down iterative enhancement and stepwise reﬁnement, and environments controlled by rule-based editors, as the most promising” Hamlet, Richard. 'A Disciplined Text Environment.” Apr. 1986 ▸ “documentation must be iterative to serve as systems communications within the development process” ▸ recommendation: “techniques and tools valuable in controlling software development be investigated for improving document preparation”

Slide 63

Slide 63 text

EXERCISE: LET’S LINT

Slide 64

Slide 64 text

Slide 65

Slide 65 text

LOOK OVER THE TELEPHONE COPIES OF YOUR DESCRIPTION WHAT PARTS OF YOUR ORIGINAL DIDN’T MAKE IT THROUGH? DID ANY OF THOSE PARTS GET CALLED OUT BY LINTERS?

Slide 66

Slide 66 text

LET’S LINT alex: alexjs.com/#demo (WEB DEMO) TextLint: textlint.github.io/playground/ (WEB DEMO) Write Good: github.com/btford/write-good (CLI TOOL) Proselint: proselint.com/write/ (WEB DEMO) Run them both through some of the linters Go to a job hunting website   (I recommend stackoverﬂow.com/jobs) Find 1 posting that would interest you Find 1 posting that looks like a nightmare

Slide 67

Slide 67 text

WHAT STANDS OUT?

Slide 68

Slide 68 text

THIS IS FOOLPROOF, RIGHT?

Slide 69

Slide 69 text

No content

Slide 70

Slide 70 text

VERY GOOD

Slide 71

Slide 71 text

IT IS DIFFICULT TO PROGRAMMATICALLY DETECT SOMEONE BEING AN A-HOLE

Slide 72

Slide 72 text

…THERE IS THE WIDESPREAD BELIEF THAT FOLLOWING RULES AND/OR FORMULAS WILL NOT GUARANTEE A GOOD PRODUCT. HOWEVER, A PIECE OF WRITING CAN BE ERROR-FREE AND STILL NOT COMMUNICATE EFFECTIVELY Technical Writing for Software Engineers: Linda Levine, Linda H. Peasant, Susan B Dunkle PERHAPS MORE GRACEFULLY STATED

Slide 73

Slide 73 text

HOW DO I GET EXPERIENCE? SO…

Slide 74

Slide 74 text

WRITE THINGS

Slide 75

Slide 75 text

GETTING EXPERIENCE REQUESTS FOR COMMENT (RFCS) https://buriti.ca/ teammates review and comment (we use Google Drive) write a proposal respond to suggestions/responses

Slide 76

Slide 76 text

GETTING EXPERIENCE REQUESTS FOR COMMENT (RFCS) speakerdeck.com/buritica/technical-decision-making-for-teams

Slide 77

Slide 77 text

LAST EXERCISE: WHAT WORKS FOR YOU?

Slide 78

Slide 78 text

THANK YOU SLIDE https://bit.ly/2K4ETwB List of Resources: Meeka Gayhart @ccanduc