00:00:16.400
how's it going my name is kevin burke i work on the api team at twilio for those of you that don't know
00:00:22.880
twilio offers an api that lets you make calls and send text messages really easily
00:00:28.560
if any of you want to quit rails and start working on a legacy php and python code base come talk to me during the happy hour
00:00:34.239
after the talk uh so we think a lot about documentation
00:00:39.360
because if users can't figure out how to get started with their product they can't
00:00:44.399
pay us money so we need to make sure that our documentation is doing good things it's working the way users
00:00:51.120
expect i also personally do a lot of work with new users users that are new to twilio and new to
00:00:56.800
programming in general so that sort of fuels some of the stuff we'll be talking about today
00:01:02.879
all right what we'll be talking about we're going to talk about why people don't read your documentation we're going to try to develop a theory
00:01:08.960
for why users how users go through your product how they sort of go through how they experience errors
00:01:14.960
how they solve those problems that they run into we'll also talk about some tips for making your documentation more usable
00:01:22.080
we'll talk about some tips in general for working around this problem that people not reading your documentation uh we're not going to talk
00:01:28.960
about motivating you to write documentation this is a journey you'll have to go on on your own you should write some you
00:01:34.799
should write documentation we're also not going to talk about there's a lot of evidence that if you design a simpler interface
00:01:43.600
you will reduce the support load your product will be more intuitive etc etc that's just outside the scope of this
00:01:49.280
talk but is also a useful skill this is also not a talk about people
00:01:54.720
that are actually illiterate as fascinating as that would be to learn about
00:01:59.840
it's just about more about general browsing on the internet than it is about illiterate users all right
00:02:07.360
so once upon a time people wrote documentation that nobody read how do i know that
00:02:12.800
people wrote documentation that nobody read that nobody's reading your documentation because nobody reads anything on the
00:02:18.319
internet so um it's safe to say that uh once your concept has made it into the
00:02:23.920
onion uh sort of jump the shark and it's something that you need to be thinking about when you're writing content for
00:02:29.680
the web so the sort of definitive resource here is an article by
00:02:35.280
a usability researcher named jacob nielsen he wrote this article called how user
00:02:40.640
read on the web the conclusion of the article is that users don't actually read they scan right if they can't find the
00:02:47.040
answers they're looking for when they're scanning your content they just leave right they go and find another resource they try to find some
00:02:52.879
other place that has an answer to their question this article was written in 1997 it's more relevant than ever today especially
00:02:59.120
when people have mobile devices they have notifications they're getting notifications all the time
00:03:04.640
for content increasingly distracted i'd encourage you to take a look at this it's excellent we're going to cover some
00:03:09.920
of the basics of this today so this is an example that nielsen did this is an eye tracking study so
00:03:16.000
they put these sophisticated devices that measure where your eyes look on the page um in this case they're just they just
00:03:22.400
ask users to solve a simple task right find some information and then watch their eyes as they do it right and you can see there's a f-shaped
00:03:28.080
pattern here users start looking in the top left they scan across to the right hand side of the page
00:03:33.200
maybe if you're lucky they scan across one more time then it's generally straight down the left-hand side of the page looking for information relevant to
00:03:39.840
their topic so you'll notice here one of the key things is that even within one con one block of content like a headline uh
00:03:47.760
the amount of fixations the amount of attention from the user varies uh so like the left hand side of
00:03:53.120
stuff is is generally more important than the right even within a single document
00:03:59.360
um so yeah so what do readers actually look at you can browse through this list here it's also
00:04:06.159
useful to think about what users aren't looking at they're not looking at big blocks of
00:04:11.760
paragraphs right if you have two ideas in a paragraph it's safe to assume that the user is not even going to see that second idea
00:04:18.079
instead split it out add a new line break it up into a new paragraph right users are also not looking at
00:04:23.759
anything that looks like marketing copy anything that looks like an ad for example so if you have a call to action
00:04:29.520
that's embedded in an image it's safe to say that your user's probably missing it right you don't have a lot of attention
00:04:36.479
you don't have a lot of room for for error on the web
00:04:44.560
this is another example from nielsen this is actually from the article how users read on the web
00:04:50.720
where they gave users a symbol piece of text that was formatted in two different ways
00:04:56.000
that you know they split up the users into two groups and they quiz them on it later this is an article about state parks in nebraska
00:05:02.080
so they said you know how many state parks are there in nebraska what are the names of the state parks et cetera et cetera then measured their attention right like
00:05:08.479
how much did users actually remember when the text was formatted in these different ways can anyone guess which
00:05:15.440
version did better the left version or the right the content
00:05:21.680
the left right the left version did better uh it's safe to say it's pretty easy can anyone guess how much better the
00:05:27.600
version on the left was in terms of performance users performance on the content like in a percentage like
00:05:35.360
three times as much 90 70 percent uh so it turns out it's
00:05:41.520
actually 125 percent as good uh the left version that's like 2.25
00:05:46.960
x improvement of the version on the left and the version on the right they're doing three specific things the
00:05:52.000
version on the left uh it's shorter right so they took out the two sentences at the beginning have a lot of fluff
00:05:57.680
content they really condensed that down into a shorter version they also made the text more objective uh it turns out that phrases like draw
00:06:04.880
crowds without fail turn off users right um they sound like marketing copy they sound like not
00:06:09.919
answers to my question so users tend to not pay attention to words like that uh they also made it scannable right so we can browse right
00:06:16.560
down the left-hand side see the beginning of every name that's there you get into the bullet point it's
00:06:22.720
pretty easy to see all of the content right there so let's look at some examples i pulled
00:06:29.120
some examples from around the web just some documentation that observes and fails to observe
00:06:34.479
these sorts of principles my apologies if any of your documentation comes up during this uh
00:06:40.400
chat okay so let's uh let's dig right in here so this is an example github readme um they're using the like readme without
00:06:46.880
a file extension or readme.txt format and the problem here is that fixed width texts tends to be very difficult to scan
00:06:53.680
at a glance right all of the letters are exactly the same width the line heights are almost similar for
00:07:00.080
the lowercase and uppercase letters the like headlines are the same size as the body content it makes it more
00:07:05.680
difficult to scan and read what's going on right instead use the default markdown format use the advantages of html as
00:07:11.520
it's given to you right use bold use links use headings separate out that content right so if
00:07:16.960
you're writing for github if that's your primary entry point into your documentation use the default markdown
00:07:22.560
format right use what's presented to you in that case this is actually from twilio's
00:07:28.000
documentation i mentioned earlier that users tend to ignore things that look like ads
00:07:33.680
is there anything on this page that looks like it could be an ad
00:07:40.400
the stuff in red right it's a giant banner it spans the entire page it looks like content that you might want to ignore
00:07:45.840
the irony here is that this is actually the content that we wanted to call out the most right it's in red
00:07:50.879
it's a banner but i've seen multiple times in user testing people just tend to ignore that section
00:07:56.479
an improvement here might be just using a red exclamation point icon maybe some bold and red text just as
00:08:02.080
warning you know hey you should probably pay attention to this and kill the red background on the banner
00:08:08.879
this is another example so this is primarily okay except that the lines are just too long
00:08:14.800
right if you think about readers as browsing down the left hand side of your content if the line is too long there's just a
00:08:20.400
lot of text that they're missing on the right hand side it's just two it's just too far for the
00:08:25.759
reader to browse across see all the content it's too easy for them to miss content that's there um it's too hard to parse the line when
00:08:31.759
it's this long just because you have this much space in the browser doesn't mean you need to use all of it right uh add generous margins to your
00:08:38.640
content and people will be happy so this is an example from github
00:08:44.159
i like this for a few reasons one is that they're breaking up the content often right the paragraphs are short they're
00:08:50.000
breaking up the content with code samples they're using headings they're using bold they're using links these are all
00:08:55.360
very nice things that make this pleasing to read when you're getting started the other
00:09:00.640
reason i like this is because they're embedding structure into the document by adding step numbers to the
00:09:06.880
headings so let's say i was scanning through this document for an answer to my question i scanned all the way straight down to
00:09:12.800
step four type something into my terminal and it stopped working that's a that's a cue for me that maybe
00:09:18.240
i should go back and read step one step two et cetera before i attempt step four
00:09:24.640
here's another example this is from heroku i like this because they put the table of contents right at the top so
00:09:30.399
this is where you are likely as a user to pay the most attention they put the most important information
00:09:36.160
to get you as fur as far as they can into the document right there at the top of the page
00:09:42.720
they could do a little bit of work on their information sent this idea that we want to put the most important words at the beginning so for
00:09:49.200
example here they have this phrase store your app in git right the important word there is git
00:09:54.560
that's what i would key on similarly with word gem file with the word proc file these are the words that i would be
00:09:59.760
keying on as a user we should put those at the beginning of the line right for example use get to track revisions
00:10:05.360
in your application makes it much easier for someone scanning down the left-hand side to see that's the content that they want to
00:10:10.800
look at another usability principle is that users are really bad at searching for
00:10:16.959
content the irony here is that as google gets better and better users faith and
00:10:24.240
like trust in google grows and the problem is that if google doesn't return an answer to
00:10:30.079
their query they tend to think that the answer does not exist right where a simple modification to the query
00:10:36.160
might return the answer that they're looking for right instead users tend to be very stubborn um persist with a query and then say
00:10:42.000
well if the answer isn't on the page then it must not exist right no one must have have an answer to my question
00:10:49.279
so here's a quote from jeff atwood he's one of the founders of stack overflow this is talking about duplicates you
00:10:54.800
might have had the experience of asking a question on stack overflow which is a question and answer site and having the answer be
00:11:00.720
rejected as a duplicate a while ago they had an epiphany and said well
00:11:05.920
maybe the answer is the same answer for a few different types of question but if users are using different words to
00:11:11.120
search for the content then we want to have a different answer for each type of user right we want to be able for the user to match
00:11:17.839
on the question type and and make sense of it that way in a podcast they mentioned they they shoot for about four different versions
00:11:24.160
of popular questions that tends to be the number of different ways people search for the same information on that
00:11:30.240
page an example of this from our own website
00:11:37.279
at twilio is we use this word called helper libraries this phrase to describe we have these
00:11:42.720
library bindings in php and python and ruby that sort of wrap our http api and give
00:11:47.920
you nice objects that you can use to sort of script twilio but i've seen it referred to as
00:11:53.600
all of these different words and so we need to think about as content producers is if a user is
00:11:59.839
searching using this word to try to find the library name are they going to be able to find it are they going to be able to find what
00:12:05.600
they're looking for are they going to make it to our site what we've ended up doing to get around this
00:12:10.880
is referring to the languages specifically right using the words ruby python php because it tends that people
00:12:16.079
searching for those words can you know know and click to go right to the spot where they want to go to
00:12:22.639
so what does what is the implication of failure in this case how will it manifest itself um you may get additional support
00:12:30.160
queries if your documentation is confusing people can't find the answers they're looking for they're going to ask you
00:12:35.600
right that's an increased cost for you right if you're a big company you need to hire someone to answer all these
00:12:40.639
questions if you're an open source developer this is super annoying because you probably have a day job and you don't want to spend time away
00:12:46.720
from your kids et cetera answering questions on the internet it's also expensive right imagine i
00:12:52.639
signed up for a service i tried to get started with it and then i couldn't right i walk out the door uh that's money out the door for
00:12:58.880
you so that's not a great solution either for you it's also frustrating for users right as
00:13:05.440
a user if i can't find the answer i'm looking for i get very frustrated right this is why i post angry tweets on the internet
00:13:11.279
and consider quitting the software industry is when stuff like this happens so uh so yeah so it's frustrating on
00:13:17.760
both ends when users can't find answers to their questions so why does this happen let's
00:13:22.880
try to develop a model for the sort of disconnect between writers and readers
00:13:28.800
this is a guy named clay christensen he's a professor at harvard business school very smart guy he has this theory he
00:13:35.279
talks about a lot called jobs to be done bear with me if you've heard this before but the idea here is that
00:13:43.279
traditionally when we're marketing a product you think about we have this product now who should we sell it to right what groups would be
00:13:49.600
interested in this so then you pick a demographic like single moms you know ages 25 to 49
00:13:55.040
or uh ruby developers on the west coast and then you go and target the product and say hey single moms you know
00:14:00.720
i think you'd be interested in this you know check it out um christensen advises flipping this on its
00:14:06.000
head so instead of uh starting with the product and then finding people who might be interested in it
00:14:11.600
let's see how people are using this right let's see what means this is fulfilling in someone's life
00:14:16.880
and then and then target our product position our products to make sense for them so as an example he gives milkshakes so
00:14:24.560
there was a fast food company that wanted to improve the sales of its milkshakes so instead of targeting this
00:14:30.720
to you know let's go sell this to teens let's go sell this to whoever they said uh why do people drink milkshakes and
00:14:36.800
the answers came out in two different ways when commuters bought milkshakes they wanted a thicker milkshake they wanted something to keep them busy
00:14:42.880
during the commute they could drink it with one hand and put off their hunger for just a little bit they like little bits of fruit in the
00:14:48.320
milkshake etc right but when parents bought milkshakes for their kids they
00:14:53.360
wanted a less thick milkshake right they didn't want a thick milkshake otherwise their kid would be sitting there trying to
00:14:59.040
drink this milkshake for 30 minutes uh you know late for soccer practice and all that sort of thing
00:15:04.240
so it's the same product right a milkshake but by looking at it by who's using it and what their sort of
00:15:09.680
needs are it ends up with two different implications for a very similar sounding thing
00:15:19.279
so let's apply the same theory to our documentation generally when we're writing
00:15:24.399
documentation we maybe just finished version one of our product we have full knowledge of the product in our head it solves our use case that's
00:15:31.040
why we wrote it and we're sitting down to you know write this full documentation we're starting
00:15:37.040
at the top writing all the way through compare that to the reader right the reader's trying to fulfill a need in their life
00:15:45.040
they're browsing maybe 10 different things they're considering different options there's there's a disconnect there between the way that we write
00:15:50.800
documentation the way that we're reading it right instead of writing documentation as we've got this product let's see who
00:15:56.320
might be interested in it uh flip that on its head and say how would people use this what need is this fulfilling in people's lives um
00:16:04.240
how is this going to help people so let's take a look at this so as an
00:16:10.079
example of a job to be done um a significant portion of numbers at twilio the way people use numbers at
00:16:15.360
twilio there's just a forward to their cell phone right they purchase a number from us they forward it for their cell phone
00:16:20.639
i spoke with a guy recently who runs a pedicab company in four different cities in the u.s and
00:16:25.680
all he wanted was just a local number so that people could call you know a 415 number in san francisco
00:16:30.959
and it would forward to his cell phone he could then dispatch a driver to pick them up he wasn't very technical right he just
00:16:36.320
wanted a solution to this problem this is what he was using twilio for and if you looked at our documentation at
00:16:41.839
the time say how to do everything with an incoming call you know here's what the twilio http request will
00:16:48.079
look like here's what your response should look like in you know xml format uh here's how to do a voicemail here's
00:16:53.759
how to do conference calls here's how to queue people we didn't really have a solution for this very easy use case
00:16:59.759
that could potentially make us a lot of money right by thinking about this you know by putting links in our
00:17:04.799
documentation to say hey if you're not technical you know here are some things you can do that are pretty easy right here are some
00:17:10.319
tools we offer to make this really easy for you this is something you can think about as you're writing documentation
00:17:17.199
here's another example this is also from twilio this is a first page of a quick start this page is actually a complete failure
00:17:24.559
so if you look at it the person who is writing this this is the first page of six
00:17:30.240
they're sitting down and imagining a a reader as someone who would start at the first page go on to the next page go on to the next
00:17:36.720
page go on to the next page when it turns out uh users readers don't do this at all right they're looking for specific
00:17:42.400
answers to their questions heaven forbid that the answer to their question is on page four of this quick start uh no one ever gets there right we also
00:17:49.280
have this very very small call to action down here at the bottom a lot of people miss this when they're going through the quick start they
00:17:54.559
either start browsing the content on the left-hand side going back to google looking for a different answer to their question
00:18:01.679
so yeah so this is an example of how as a writer we wrote documentation that really wasn't fulfilling
00:18:06.720
a reader's need we weren't thinking about how researchers were using the content
00:18:12.640
an improvement here would just be to make this one page right put the entire quick start on one page make it easy for a reader to browse
00:18:18.720
through and scan the entire document looking for the information they wanted
00:18:24.720
another thing is that you should assume that readers are not reading any of the context surrounding your code snippets you should assume that all of your
00:18:30.720
co-snippets someone is just going to take that copy and paste it and try to run it in a terminal or in a command line
00:18:37.200
we've seen this multiple times so here's an example code snippet that we had on our site
00:18:44.000
that was also a failure so let's take a look there are actually three ways that this is going to fail the first one is assumes you've set
00:18:50.240
environment variables in your environment right if you create this rest client without any parameters
00:18:55.360
it's going to try to read stuff out of your environment a twilio account sit in an auth token and then do stuff with it this will fail
00:19:01.120
silently if you don't have those environment variables set uh it works great when you're running on heroku when you're just getting started
00:19:06.240
with the product it's a complete failure right we also have this typo and sms messages i see this often enough
00:19:12.400
that it's worth pointing out it's very confusing for users because they copy and paste this off your website expect it to work and then it completely
00:19:18.559
breaks um it's a bit it's a it's a problem i've seen it all the time just make sure that
00:19:24.160
your your documentation and code samples are free of these sorts of typos finally we've forgotten the uh the
00:19:29.360
require line at the top of the file that's going to require the library if user is going to copy and paste this they'd get an uninitialized constant
00:19:35.360
error when they're trying to run the sample so a simple code snippet right it was going
00:19:41.039
to fail in three specific ways it's going to generate a lot of frustration for your users
00:19:46.240
a lot of frustration when you're going through this uh here's the betterment it's cut off a little bit on the right
00:19:51.840
hand side but the idea is it's not much more work right it's just three lines this will actually work
00:19:57.360
when you copy paste it into the browser we've also put the context right there this is where you can get the twilio ruby library we also have more
00:20:04.000
information at the link about how to use the library some sample actions how it handles errors that sort of thing
00:20:16.960
this is another example i thought i'd point out because i see it often enough people copying and pasting if we try to
00:20:22.960
run this in a terminal i've seen people copy and paste this the first thing they get is this
00:20:28.559
they try to run this with a dollar sign and then you know the dollar sign obviously isn't a command so it just fails i don't have great ideas here because
00:20:35.360
there's also a convention that if a line doesn't begin with a dollar sign then it's you know output from a command or it's something you're
00:20:41.360
supposed to copy and paste and put in a text editor it's just something to look out for especially when you've got new users
00:20:47.600
on the command line this is a big problem yep go for it what's up
00:20:57.760
so it's usually the beginning of a terminal prompt like a naked terminal prompt that you get when you start with the terminal
00:21:03.200
it's generally the left-hand side so that's like the idea is that it's the beginning right sometimes you see a pound it's supposed to be the
00:21:08.720
root user right on the left-hand side of the right right uh so yeah so
00:21:16.880
anyway just something to think about when you're writing documentation is that i've seen this problem happen uh more or
00:21:22.320
less every week at twilio so how can you find out what your users are trying to do how can you
00:21:28.240
find out what phrases they're thinking of what their mental model is the short answer is they're going to
00:21:34.159
tell you right you can look at your support questions you can look at your forums and say what questions our users
00:21:39.840
are users asking right how are they phrasing their questions what are they trying to do right they'll start with a question says i'm trying to
00:21:45.520
do x y and z well think about that right that's an example use case that your documentation can solve
00:21:50.960
here this is google analytics i've just set up a very simple filter that says everyone that lands on our documentation what search queries did
00:21:57.679
they use that got us to this page what were they actually searching for that landed them on our documentation
00:22:03.039
right what words were they using uh there are two specific things that came out of this first one is we saw people were using uh
00:22:09.760
languages very often right so they're searching for php sms so they're searching for ruby call right how do i do this in
00:22:16.480
a specific language so we did is we put the languages right inside the documentation so that people could see the code
00:22:21.679
samples right there right they didn't want to know necessarily about the raw http reference this said it was you know how am i
00:22:28.000
actually going to be sending this message what code am i actually going to be typing into my browser to make this work
00:22:35.120
second one was we saw that people were using verbs right people were saying php schedule call right or uh php send
00:22:42.320
sms right they're using these verbs to search for things so the betterment here was uh we put
00:22:48.240
uh on the homepage we put a list of verbs right a list of actions that you can take just trying to match people scanning
00:22:53.919
this right and looking for actions to take they'd hopefully key on one of these
00:22:59.200
and go off to the right page if you do actually look at this on our homepage a lot of these links go to the same
00:23:04.240
pages we're just trying to match on whatever the user is trying to do right and send them to the right place based
00:23:09.280
on that okay so we can think about this right if
00:23:16.480
we think about our users right if we try to develop a model the user going through our products right or trying to get
00:23:22.080
something done we can think about it as a user has a goal they have something they're trying to do and then they fail right and then they
00:23:29.120
go off in the wilderness and look for help and then figure out how to solve the problem or quit the software industry
00:23:35.280
entirely and then come back right and and continue along the path right similar to like games right you know you go and
00:23:42.000
you die a few times and then you get better and end up defeating the boss at the end of the level um thinking about clay christensen
00:23:49.360
theory every time a user fails uh they're looking for a need right they're looking for something to help
00:23:54.480
fill that void they're looking for something to help them get through that problem right if you're writing documentation or
00:24:00.640
you're evaluating a product you should be there right you should be there to help your user your resources
00:24:05.760
should win right when your users are looking for help your documentation should be the first
00:24:12.720
thing that's on their mind let's look at some examples of this so this is an example error
00:24:18.159
that our users were getting a lot when they tried to run the ruby quick start right so some of you might know what
00:24:23.279
this means let's all pretend that we had no idea what this means we were trying to write some code in the command line hit enter
00:24:29.120
and then this happened right so what would you do if you got this error message what would you do right if you got this
00:24:36.880
google it right you'd punch us into google okay so let's say we copy and paste this uh we add in some words that are
00:24:42.320
specific to us like twilio and ruby and we search for it on google right here's what we get
00:24:47.760
the first result is from stack overflow the second result also from stack overflow the third result is a twilio forum post
00:24:54.159
from 2011 may have an answer may not uh may have an answer that's up to date this is unclear right the third answer
00:25:00.799
is a third party twilio library it's not an official twilio library it's also a github issue again it may have an
00:25:06.159
answer to the question may not may have an up-to-date answer to the question unclear the fifth post is from a blog post uh
00:25:13.760
explaining how to get started on heroku um also from 2011 right
00:25:19.520
so the problem is that our documentation is not here right we've completely failed for the
00:25:24.640
user who's trying to find an answer to this question we're not we're not even in the user's mind here uh
00:25:30.799
we're nowhere to be found right we're not providing an answer we're not helping the user there's an obvious betterment here which
00:25:36.720
is users get an error message a lot put that exact text in your documentation for us about 45 percent of our users i
00:25:44.080
checked over the weekend are coming straight from google right on an average day this means that 45 of people browsing to our
00:25:49.919
documentation coming directly from google to our docs right uh and if our documentation is not
00:25:55.039
matching this query then our users are missing out right they're not going to find our
00:26:00.480
documentation they're going to go off to a third party page we've lost control over that experience we lost control over the experience user
00:26:06.720
has getting started with their product here are some examples of failures so
00:26:11.840
this is a company i pulled off the internet they put their documentation behind a login wall
00:26:18.480
right so you have to sign in or register to see this the implication is that google can't find their documentation can't index their documentation
00:26:26.799
so this essentially means to the 45 percent of hits might be going to this documentation right
00:26:32.080
even though their users are you know might have login credentials the when they run into problems and search for them on google the answers
00:26:38.480
they find are not going to be available on this company's website right they've essentially blocked off all of that traffic that's coming from
00:26:44.320
google redirected them to third-party sites right there might be a legitimate business reason to restrict access to
00:26:49.679
your api but your documentation should at least be indexable by google
00:26:54.880
otherwise you're leading users down a crazy path uh into third-party user space here's
00:27:00.640
another example pdfs right so click here to download our api documentation as a pdf
00:27:07.440
uh this is not a good experience for two reasons one is google tends to not index pdfs as well as it does
00:27:13.679
actually html it's super annoying to scan through this as a user and scan
00:27:19.760
through pdfs right searching doesn't work as well pdf as it does in the browser finally uh it's harder to regenerate
00:27:26.240
pdfs than it is like a cms or a web page right you got to find the guy that has the magic pdf building
00:27:31.919
incantation or adobe whatever and get him to rebuild the docs and and put it up on the website this page
00:27:37.919
is also a mess you can see there's a huge block of text going across and a lot of marketing content on this
00:27:44.159
on this page so the betterment here is you know put your documentation in html put it in a website
00:27:50.640
this is a great example this is from google closure so if you use google closure they're like javascript framework
00:27:56.000
and you get an error they've put this error reference page up it's got both the tokens that you'd be
00:28:01.279
that you'd find right in the error page as well as the actual human readable text of the error message
00:28:06.399
right there on the page so if i got a shift amount out of bounds error when i was using google closure i type
00:28:12.399
it into google i get straight to this page it explains you know what went wrong and how to fix it i can go back and fix the
00:28:18.080
problem and then i'm uh i'm back as a happy developer right this is a great experience
00:28:26.000
when you're using google if they can't figure out how to solve your problem at least i've got this documentation page here
00:28:31.039
that's ready to help you out um so this is a company called wikihow
00:28:36.240
right i'd like to just point out that google search traffic is pretty valuable and if you're not thinking about it then
00:28:41.520
other companies will so these are some guys that noticed that people were searching for twilio related phrases a lot they put out this simple page about how
00:28:47.919
to validate requests from twilio this is not a great experience for our users right we don't want our users to go to this
00:28:53.440
ad field page that might be up to date it might not right the good news is that if you have scannable content indexable content
00:29:00.799
you're generally going to win right hopefully you have a domain that's it's pretty high in seo for your own company name right so uh so
00:29:08.080
your documentation should win but this is just something to keep in mind that if you're not on google other companies
00:29:13.360
maybe and they may be getting this traffic that that's not great for your for your user experience
00:29:21.120
okay so we've put this error message in our documentation um that's great right a user
00:29:28.159
gets a failure they search for it find the answer uh go back to programming great uh why not
00:29:33.760
go further right why not see if we can can nip this even further develop a faster feedback loop
00:29:40.720
so here's this error again does anyone know actually why this is why this is caused why a user might run into this
00:29:50.000
invalid ssl certificate right so so a user has an old server that doesn't have an up to date see a cert list
00:29:56.880
they try to make a request to api.twilio.com it doesn't match with the certificates they have on the computer
00:30:02.000
and then and then the certificate fails and the request fails right not a great experience for the user so
00:30:07.600
we ended up doing is we ended up just shifting shipping our own certificate list with a
00:30:13.120
library so the library now is going to use our own certificate to validate requests instead of the
00:30:19.760
random whatever certificate happens to be on the server right we've obviated the need for documentation in this case
00:30:26.240
uh we've just eliminated the problem for the user this is a much better experience for the user
00:30:31.360
than having to go through that feedback loop
00:30:37.120
here's another example this is from rvm this is the rvm installation process
00:30:43.679
this is a great experience because the command line is a pretty scary place especially for new users it's hard to
00:30:49.120
get started the error messages are very obtuse it takes a while to figure out if you
00:30:54.640
guys remember the early days of learning how to program on the command line so what the rvm people said is we're tired of dealing
00:31:00.559
with installation problems we're tired of dealing with misconfigured statuses so let's just make our own install script
00:31:06.080
right let's install it uh what we can do then is we can customize the error messages that come out
00:31:11.200
uh we can take care of things like making sure it's installed in the right place making sure we have permissions etc
00:31:16.640
before we get started here there is a security problem here where it's not particularly great to have
00:31:24.080
users trusting random scripts they download off the internet and running them on their computer i i don't have enough time to get into
00:31:31.120
it suffice to say that like programming on the command line is is difficult enough for new users that i'd recommend doing this
00:31:37.039
it's like a poor man's pkg or dmg installer so yeah so this is a way to get around
00:31:44.320
that problem another thing we can do is uh add
00:31:49.440
documentation to our validation right if you think about causes of user failure a lot of it is sending bad input
00:31:55.120
to your api sending bad input to your interfaces et cetera right john dahl talked touched on this a
00:32:00.559
little bit earlier today we can document how to fix the errors right there in our documentation
00:32:06.559
so this is an example from a product we have called hurl.it just lets you make http requests in the
00:32:12.480
browser view the responses right there on the page
00:32:18.320
so if you send it a bad url to go fetch we'll say that's weight what right which
00:32:24.399
is not a very clear error message doesn't explain what actually went wrong right if i read this it could be a server error
00:32:30.159
uh it could be any number of different things right it's not clear what actually failed in this case this uh error message
00:32:35.760
doesn't instruct the user how to solve the problem at all it's pretty frustrating so what's
00:32:41.279
the betterment here instead of saying you know that's weight what let's say if the url was bad let's explain that
00:32:47.600
the url was bad if you didn't include a url let's say please include a url if the url was malformed for whatever
00:32:53.519
reason let's say the url wasn't valid right let's also put the url whatever the user gave us right back
00:33:00.080
into the string this is valuable in places like where you have an api let's say you're accepting input from a user
00:33:06.159
and then sending it to an api you might not even see the data right you might just be a transparent pass-through
00:33:11.679
so if you get back a message it just says the url is invalid you're not going to know which url it
00:33:17.679
was that was invalid you're not even going to know what the user input was by putting that error message there it makes it more likely that your error
00:33:23.600
catching is going to detect the problem and be able to fix it on the client side
00:33:30.000
we can do even better than this a lot of times when i see url validation people leave
00:33:36.080
off the scheme at the front right so people type in google.com they leave out the http at the front
00:33:41.919
and then this fails validation right this is particularly confusing because google and firefox and other browsers
00:33:47.679
will accept these urls without a scheme on the front right so in this case we can say the url was invalid but if it was valid with a
00:33:54.640
scheme at the front we can say did you mean you know http this is a way to help the user you know see this is what you need to do
00:34:00.880
to fix the problem get back on the happy path so is this amount of effort worth it
00:34:06.799
right we've turned about three lines of validation into nine or ten uh is that worth it
00:34:12.480
to me it is right if you think about the amount of work that that your team is doing in marketing and sales to get
00:34:17.919
people in the door the amount of money that you're spending an effort to do that to lose them later on down the line if
00:34:25.119
they're you know they've gotten past the point of sign up they've gotten to the point of writing code to actually use your service
00:34:30.240
to get discouraged or frustrated at this point is pretty expensive for you to have a bad experience of your product
00:34:35.520
um it's very expensive right um it's a lot of wasted effort on your part to spend all
00:34:42.000
that money getting them in the door and see them walk back out the other side
00:34:49.679
so that's great so we've looked at common errors in our documentation we've seen what people are doing to search for our
00:34:55.760
content the next step is you actually want to watch people use your service
00:35:02.560
so this doesn't need to be anything fancy you don't need a lab you don't need
00:35:07.760
sophisticated equipment you don't need to pay a company a hundred dollars to go out and find users for you to test on
00:35:13.520
all you need is just to go out and and just ask someone hey i'd like to take 30 minutes of your time i'm trying
00:35:18.800
to work on my product i'm trying to see what failures people will have in it could you help me out for a second right we
00:35:24.480
usually give out a t-shirt and some amount of free credit in our service
00:35:29.520
it's pretty simple right uh to start with just ask the simplest possible thing people can do with your with your product or with your open
00:35:35.440
source tool say do the simplest possible thing for us this is try to send an sms to your phone right
00:35:40.800
it takes about 30 minutes after you've asked the question uh be silent and get out of the way right it'll be very tempting to you know
00:35:48.000
to scream at the user and say how could you get this wrong you know just scroll down the page a little bit further you'll see the answer to your
00:35:53.440
question but i encourage you not to do that just stay out of the way or you'll never see how frustrating it is
00:35:59.839
for you to use your own product right and you'll gain a lot of insight into how people think about things
00:36:05.760
people's typical paths through your through your site through starting up just by doing this and it's pretty cheap
00:36:12.000
it's pretty cheap to get started i definitely recommend this to you as sort of the next step in your journey
00:36:18.880
all right so almost out of time here let's talk a little bit about takeaways
00:36:24.480
from today's session the first is making your documentation more readable right we talked a lot
00:36:29.680
about usability principles how people read on the internet how they scan on the internet how to write your documentation in a way
00:36:35.920
that makes sense use the use the tools that html gives you for formatting content right
00:36:41.520
use the headings use bold use links use italics break up your paragraphs right one idea per paragraph break it up
00:36:48.000
use code samples right use all these different tools to help you out the paragraphs the first three to five
00:36:53.599
words of your paragraph should have a strong information sent they should explain exactly what the
00:36:59.359
content is doing if you're curious about this go read bbc news as headlines they're always three to five words they're all excellent
00:37:05.040
right they explain exactly what the article is doing they're great models for you as you're writing documentation finally
00:37:10.960
uh 65 to 90 characters per line tends to be a good a good a good guideline right that's
00:37:16.480
about three fixations of your eye your user's eye as they're scanning across the page it's just
00:37:21.760
funny that 80 character line limits started as a technical limitation of punch cards
00:37:26.960
but actually tended to be a good readability limitation as well for how often you should be breaking up
00:37:32.160
the page and adding new lines into your content second you should care about seo
00:37:38.720
you should care about this because your users are using google a lot it's not that hard to get started i
00:37:44.000
encourage you to read the google seo guide it's a good guide to get started your url should describe the content the
00:37:49.839
headings should describe the content et cetera finally every page is a landing page right you might expect users to browse
00:37:55.040
your content starting at the root and going hierarchically down into your service that's not actually true they can land on any page
00:38:00.720
it should make sense inside the grander scheme of your documentation finally thinking about jobs to be done
00:38:06.800
right every failure for the user is a potential job to be done it's a potential fix for your users
00:38:13.119
this is something you should think about you should think about you know is my product have i designed this
00:38:18.480
around users needs have i made this make sense for my users um look at this right so you should be
00:38:25.920
able to control most user failures right control that experience that happens right even though it's on the command line
00:38:31.040
it's outside of your website you should be able to control what users see be able to help them and steer them through that process of using your site
00:38:38.079
the good news is as a documentation writer even if you're not technical error messages tend to be a great place to get started with a
00:38:44.400
product because you can search for them you can fix them and change them without understanding really anything about the
00:38:51.119
surrounding code base right open source developers tend to like these changes make error messages more clear it's a
00:38:57.280
great way to get started with a new project or even within your company right if you're a product manager a salesperson
00:39:02.800
you know getting started with the code base and trying to help improve things the error messages are a great place to start
00:39:09.599
finally if you have a chance just fix the problem for the user don't even let them run into it fix it before it starts is another thing
00:39:15.119
that you can do to improve your documentation right just obviate the need to document anything at all it's a great place to
00:39:21.440
fix that that's all the time i have like say thanks very much you've been a
00:39:26.560
great audience i know there's like happy hours and stuff around the way so i appreciate you guys being here the slides are available
00:39:32.640
online and i'm happy to take any of your questions okay thank you very much thanks for
00:39:40.839
coming how's it going
00:40:17.280
you