Writing So Your Words Are Read — DevOpsDays Boston

D E VO P S DAY S B O S
TO N T R AC Y O S B O R N @limedaring Writing So Your Words Are Read   How to write documentation and content that everyone would want to read and can understand.

TO N T R AC Y O S B O R N @limedaring Hi, I’m Tracy! @limedaring (daring, not darling)

TO N T R AC Y O S B O R N @limedaring

TO N T R AC Y O S B O R N @limedaring I will be tweeting all links: @limedaring (“daring” — not “darling”) #talkpay

FLU EN T CO NFER ENC E T RAC Y
OS B OR N @limedaring

TO N T R AC Y O S B O R N @limedaring Better documentation = More users. Less support requests. More contributors.

TO N T R AC Y O S B O R N @limedaring Most of these tips work   for all writing

FLU EN T CO NFER ENC E T RAC Y
OS B OR N @limedaring

TO N T R AC Y O S B O R N @limedaring We’re chatting content, not design   (and deﬁnitely not grammar.)

TO N T R AC Y O S B O R N @limedaring How do we make our content, technical writing, and documentation easy to read and enjoyable?

TO N T R AC Y O S B O R N @limedaring Creating friendly and welcoming writing.   (Let’s throw some best practices out the window.)

TO N T R AC Y O S B O R N @limedaring Remember —   your readers aren’t you.

TO N T R AC Y O S B O R N @limedaring Write like a human, not a machine.

TO N T R AC Y O S B O R N @limedaring But… avoid cultural references since they won’t translate.

TO N T R AC Y O S B O R N @limedaring Requests is the only Non-GMO HTTP library for Python, safe for human consumption.

TO N T R AC Y O S B O R N @limedaring Try personas — create a character and write for them.

TO N T R AC Y O S B O R N @limedaring “What would Fred (a designer working on his ﬁrst programming project) need to know?”

TO N T R AC Y O S B O R N @limedaring This document discusses using various kinds of authentication with Requests. Many web services require authentication, and there are many diﬀerent types. Below, we outline various forms of authentication available in Requests, from the simple to the complex.

TO N T R AC Y O S B O R N @limedaring Remember that terms that are obvious might not be obvious to others.

TO N T R AC Y O S B O R N @limedaring “Cream the butter”

TO N T R AC Y O S B O R N @limedaring “Cream the butter” “Truss the bird”

TO N T R AC Y O S B O R N @limedaring “Cream the butter” “Truss the bird” “Fold the egg whites”

TO N T R AC Y O S B O R N @limedaring “Cream the butter” “Truss the bird” “Fold the egg whites” “Render the fat”

TO N T R AC Y O S B O R N @limedaring “Cream the butter” “Truss the bird” “Fold the egg whites” “Render the fat” “Shock the vegetables”

TO N T R AC Y O S B O R N @limedaring Link anything that you   don’t want to explain.

TO N T R AC Y O S B O R N @limedaring To get someone started with your project: teach — don’t tell. http://stevelosh.com/blog/2013/09/teach-dont-tell/

TO N T R AC Y O S B O R N @limedaring The son says: “Hey Dad, you said you were going to teach me how to drive after school today. Are we still going to do that?” The father, without looking up from his iPad, replies: “Of course, son. The car is in the garage and I laid out a set of wrenches on the workbench. Take the car apart and look at each piece, then put it back together. Once you’ve done that I’ll take you to the DMV for your driving test.”

TO N T R AC Y O S B O R N @limedaring Reading the source works for someone already familiar with your project. Your writing about your project and documentation needs to get them to that point.

TO N T R AC Y O S B O R N @limedaring Dumb things down   (without making them dumb.)

TO N T R AC Y O S B O R N @limedaring Use gender-neutral language.

TO N T R AC Y O S B O R N @limedaring Try to avoid pronouns or rewrite your sentences to use plural pronouns. More: http://techwhirl.com/gender-neutral-technical-writing/

TO N T R AC Y O S B O R N @limedaring Overwhelmed?

TO N T R AC Y O S B O R N @limedaring Overwhelmed? 1. Take a break.

TO N T R AC Y O S B O R N @limedaring Overwhelmed? 1. Take a break. 2. Have a friend review your writing.

TO N T R AC Y O S B O R N @limedaring The basics of   writing clearly.   (Shorter is better, yo.)

TO N T R AC Y O S B O R N @limedaring Cut down your content.   Two to three sentences per paragraph.

TO N T R AC Y O S B O R N @limedaring Break into bullets and use lots of headers. Make it easy to skim.

TO N T R AC Y O S B O R N @limedaring Use italics and bolding to   break up paragraphs.

TO N T R AC Y O S B O R N @limedaring We made a bunch of changes: The registration chapter has been split in two, between adding registration and then associating users with objects. The chapter was giant before so this makes it more manageable. Screenshots of the admin have been updated to reflect the new Django 1.9 styles. The few minor typos have been fixed. Updated the version of django- registration-redux that we use to 1.3. Last but not least, the Introduction has been updated. We made a bunch of changes: • The registration chapter has been split in two, between adding registration and then associating users with objects. The chapter was giant before so this makes it more manageable. • Screenshots of the admin have been updated to reflect the new Django 1.9 styles. • The few minor typos have been fixed. • Updated the version of django-registration-redux that we use to 1.3. • Introduction has been updated.

TO N T R AC Y O S B O R N @limedaring We made a bunch of changes: • The registration chapter has been split in two, between adding registration and then associating users with objects. The chapter was giant before so this makes it more manageable. • Screenshots of the admin have been updated to reflect the new Django 1.9 styles. • The few minor typos have been fixed. • Updated the version of django-registration-redux that we use to 1.3. • Introduction has been updated. We made a bunch of changes: • The registration chapter has been split in two, between adding registration and then associating users with objects. The chapter was giant before so this makes it more manageable. • Screenshots of the admin have been updated to reflect the new Django 1.9 styles. • The few minor typos have been fixed. • Updated the version of django- registration-redux that we use to 1.3. • Introduction has been updated.

TO N T R AC Y O S B O R N @limedaring We made a bunch of changes: • The registration chapter has been split in two, between adding registration and then associating users with objects. The chapter was giant before so this makes it more manageable. • Screenshots of the admin have been updated to reflect the new Django 1.9 styles. • The few minor typos have been fixed. • Updated the version of django- registration-redux that we use to 1.3. • Introduction has been updated. We made a bunch of changes: • The registration chapter has been split in two, between adding registration and then associating users with objects. The chapter was giant before so this makes it more manageable.  • Screenshots of the admin have been updated to reflect the new Django 1.9 styles.   • The few minor typos have been fixed. • Updated the version of django- registration-redux that we use to 1.3.   • Introduction has been updated.

TO N T R AC Y O S B O R N @limedaring Don’t forget your headlines.

TO N T R AC Y O S B O R N @limedaring Simplify your language.   Is there a more direct way to write the same thing?

TO N T R AC Y O S B O R N @limedaring Mark up your code snippets to make sure they’re styled diﬀerently.

TO N T R AC Y O S B O R N @limedaring Add ﬁlenames to code blocks   if it makes sense.

TO N T R AC Y O S B O R N @limedaring Document with pictures.

TO N T R AC Y O S B O R N @limedaring In conclusion…   (People are awesome and we want them to use our stuﬀ.)

TO N T R AC Y O S B O R N @limedaring Remember that your readers have diﬀerent backgrounds and experiences than you.

TO N T R AC Y O S B O R N @limedaring Be friendly and write like a human.

TO N T R AC Y O S B O R N @limedaring Simplify. (applies to length, word choice and complexity, layout, everything.)

TO N T R AC Y O S B O R N @limedaring Thank you! @limedaring

Writing So Your Words Are Read — DevOpsDays Boston

Writing So Your Words Are Read — DevOpsDays Boston

More Decks by Tracy Osborn

Featured

Transcript