Slide 1
Slide 1 text
NO DE CONF BUDAPE ST
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.
Slide 2
Slide 2 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
Hi, I’m Tracy!
@limedaring
(daring, not darling)
Slide 3
Slide 3 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
Slide 4
Slide 4 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
Slide 5
Slide 5 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
Slide 6
Slide 6 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
• Too long and wordy.
Slide 7
Slide 7 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
• Too long and wordy.
• Too technical and complex.
Slide 8
Slide 8 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
• Too long and wordy.
• Too technical and complex.
• No pictures.
Slide 9
Slide 9 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
• Too long and wordy.
• Too technical and complex.
• No pictures.
• Outdated.
Slide 10
Slide 10 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
• Too long and wordy.
• Too technical and complex.
• No pictures.
• Outdated.
• Incorrect directions.
Slide 11
Slide 11 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
• Too long and wordy.
• Too technical and complex.
• No pictures.
• Outdated.
• Incorrect directions.
• No documentation at all.
Slide 12
Slide 12 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
Slide 13
Slide 13 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
Better documentation and writing =
More users.
Less support requests.
More contributors.
Slide 14
Slide 14 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
Slide 15
Slide 15 text
NO DE CO NF ARGENTI NA
T R AC Y O S B O R N @limedaring
Slide 16
Slide 16 text
NO DE CO NF ARGENTI NA
T R AC Y O S B O R N @limedaring
Slide 17
Slide 17 text
FLU EN T CO NFER ENC E
T RAC Y OS B OR N @limedaring
Slide 18
Slide 18 text
FLU EN T CO NFER ENC E
T RAC Y OS B OR N @limedaring
Slide 19
Slide 19 text
FLU EN T CO NFER ENC E
T RAC Y OS B OR N @limedaring
Slide 20
Slide 20 text
FLU EN T CO NFER ENC E
T RAC Y OS B OR N @limedaring
Slide 21
Slide 21 text
FLU EN T CO NFER ENC E
T RAC Y OS B OR N @limedaring
Slide 22
Slide 22 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
Most of these tips work
for all writing.
Slide 23
Slide 23 text
NO DE CONF BUDAPE ST
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?
Slide 24
Slide 24 text
NO DE CONF BUDAPE ST
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.)
Slide 25
Slide 25 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
Remember —
your readers aren’t you.
Slide 26
Slide 26 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
Slide 27
Slide 27 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
Slide 28
Slide 28 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
Slide 29
Slide 29 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
Write like a human, not a machine.
Slide 30
Slide 30 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
Slide 31
Slide 31 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
But… avoid cultural references since
they won’t translate.
Slide 32
Slide 32 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
Slide 33
Slide 33 text
NO DE CONF BUDAPE ST
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.
Slide 34
Slide 34 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
Try personas — create a character
and write for them.
Slide 35
Slide 35 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
“What would Fred (a designer working
on his first programming project) need
to know?”
Slide 36
Slide 36 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
Remember that terms that are
obvious might not be obvious
to others.
Slide 37
Slide 37 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
Slide 38
Slide 38 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
“Cream the butter”
Slide 39
Slide 39 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
“Cream the butter”
“Truss the bird”
Slide 40
Slide 40 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
“Cream the butter”
“Truss the bird”
“Fold the egg whites”
Slide 41
Slide 41 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
“Cream the butter”
“Truss the bird”
“Fold the egg whites”
“Render the fat”
Slide 42
Slide 42 text
NO DE CONF BUDAPE ST
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”
Slide 43
Slide 43 text
NO DE CONF BUDAPE ST
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”
Slide 44
Slide 44 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
Link anything that you
don’t want to explain.
Slide 45
Slide 45 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
Slide 46
Slide 46 text
NO DE CONF BUDAPE ST
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/
Slide 47
Slide 47 text
NO DE CONF BUDAPE ST
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.
Slide 48
Slide 48 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
Slide 49
Slide 49 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
Dumb things down
(without making them dumb.)
Slide 50
Slide 50 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
Slide 51
Slide 51 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
Slide 52
Slide 52 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
Slide 53
Slide 53 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
Slide 54
Slide 54 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
Use gender-neutral language.
Slide 55
Slide 55 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
Slide 56
Slide 56 text
NO DE CONF BUDAPE ST
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/
Slide 57
Slide 57 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
The basics of
writing clearly.
(Shorter is better, yo.)
Slide 58
Slide 58 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
Cut down your content.
Two to three sentences per
paragraph.
Slide 59
Slide 59 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
Break into bullets and use lots of
headers. Make it easy to skim.
Slide 60
Slide 60 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
Use italics and bolding to
break up paragraphs.
Slide 61
Slide 61 text
NO DE CONF BUDAPE ST
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.
Slide 62
Slide 62 text
NO DE CONF BUDAPE ST
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.
Slide 63
Slide 63 text
NO DE CONF BUDAPE ST
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. Last but not least, the
Introduction has been
updated.
Slide 64
Slide 64 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
Don’t forget your headlines.
Slide 65
Slide 65 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
Slide 66
Slide 66 text
NO DE CONF BUDAPE ST
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?
Slide 67
Slide 67 text
NO DE CO NF ARGENTI NA
T R AC Y O S B O R N @limedaring
Slide 68
Slide 68 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
Slide 69
Slide 69 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
Document with pictures.
Slide 70
Slide 70 text
NO DE CO NF ARGENTI NA
T R AC Y O S B O R N @limedaring
Slide 71
Slide 71 text
NO DE CO NF ARGENTI NA
T R AC Y O S B O R N @limedaring
Slide 72
Slide 72 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
Slide 73
Slide 73 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
Slide 74
Slide 74 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
Overwhelmed?
Slide 75
Slide 75 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
Overwhelmed?
1. Take a break.
Slide 76
Slide 76 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
Overwhelmed?
1. Take a break.
2. Have a friend review your writing.
Slide 77
Slide 77 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
In conclusion…
(People are awesome and we want them to use our stuff.)
Slide 78
Slide 78 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
Remember that your readers have
different backgrounds and
experiences than you.
Slide 79
Slide 79 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
Be friendly and write like a human.
Slide 80
Slide 80 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
Simplify.
(applies to length, word choice and complexity,
layout, everything.)
Slide 81
Slide 81 text
NO DE CO NF ARGENTI NA
T R AC Y O S B O R N @limedaring
Slide 82
Slide 82 text
NO DE CONF BUDAPE ST
T R AC Y O S B O R N @limedaring
Thank you!
@limedaring
Slide 83
Slide 83 text
NO DE CO NF ARGENTI NA
T R AC Y O S B O R N @limedaring