00:00:16.400
How's it going? My name is Kevin Burke, and I work on the API team at Twilio. For those of you who don't know, Twilio offers an API that lets you make calls and send text messages really easily. If any of you want to quit Rails and start working on a legacy PHP and Python codebase, come talk to me during the happy hour after the talk. We think a lot about documentation because if users can't figure out how to get started with our product, they can't pay us money. Thus, we need to make sure that our documentation is effective and works the way users expect.
00:00:39.360
Personally, I do a lot of work with new users—users that are new to Twilio and new to programming in general—which fuels some of what we'll be talking about today. In this presentation, we're going to talk about why people don't read your documentation. We'll try to develop a theory for how users navigate through your product, how they experience errors, and how they solve the problems they encounter. Additionally, we will cover some tips for making your documentation more usable.
00:01:02.879
We will not discuss motivating you to write documentation. This is a journey you’ll have to embark on your own. You should write documentation. We also won't be covering the evidence that designing a simpler interface can reduce the support load and make your product more intuitive; this is outside the scope of this talk but is also a useful skill. Importantly, this is also not a talk about people who are actually illiterate, although that would be fascinating to learn about. Instead, we're focused on general browsing behavior on the internet.
00:01:28.960
Once upon a time, people wrote documentation that nobody read. How do I know that people are not reading your documentation? It is because most people do not read content word for word on the Internet. Once a concept has made it into 'The Onion', it signals that you need to consider how you're writing content for the web. A definitive resource on this topic is an article by usability researcher Jacob Nielsen, titled 'How Users Read on the Web'. The conclusion of the article is that users do not read; they scan. If users fail to find the answers they seek while scanning your content, they simply leave and find another resource.
00:02:07.360
This article, written in 1997, is more relevant today than ever, especially as people increasingly use mobile devices and receive constant notifications. Given that users are more distracted than ever, I encourage you to check it out. It provides excellent insights. Nielsen conducted an eye tracking study that demonstrated how users scan the page. In this study, users were asked to solve a simple task and their eye movements were recorded. The results showcased an F-shaped pattern: users start looking in the top left corner, scan across the top, and then move down the left side of the page looking for relevant information.
00:02:52.879
One key takeaway is that within a single block of content, like a headline, the amount of attention from users varies. For example, the left side of a content block tends to be more important than the right side. Readers often ignore large blocks of text; therefore, if you present two ideas within a paragraph, it is safe to assume that users might miss the second idea. Instead, it is better to split it up and add a new line to break it into a new paragraph. Special attention is also required for anything that resembles marketing copy. If you have a call to action embedded in graphics or anything that looks like an ad, it is likely that users will ignore it.
00:04:18.079
This example is from a Nielsen article about how users read on the web, where they formatted a piece of text in two different ways to see how well users would remember it. The study measured retention by quizzing users about an article on Nebraska state parks. The question was how many state parks there are and their names. Users who read the version on the left performed significantly better than those who read the right.
00:04:56.000
Specifically, the left version was 125% more effective—an impressive 2.25x improvement over the other version. The left version was brief, objective, and scannable. It used formatting that allowed users to quickly identify important information. This highlights the importance of clarity and brevity in your documentation. Drawing from this, I’ve compiled various examples from around the web of documentation that adheres to these principles and some that fail to. My apologies in advance if your documentation happens to come up during this.
00:06:22.720
Let's start with an example: a GitHub README file that lacks formatting and utilizes a fixed width layout. This makes it difficult for users to scan at a glance. All letters have the same width, and headlines are the same size as body content, making it harder to differentiate and read. Instead, utilize the default markdown format, taking advantage of HTML to add bold text, links, and headings. This organization helps present your content effectively.
00:06:51.680
Now, let’s examine Twilio's documentation. I previously mentioned that users tend to overlook items that appear to be ads. On one of our documentation pages, there's a large red banner that spans the entire width of the page. Ironically, this is the content we want to highlight the most, but user testing has shown that many users ignore that section altogether. A potential improvement here would be to use a prominent icon or bold, red text instead of a background banner to draw attention.
00:07:38.080
It's crucial to keep paragraph lengths manageable, as long lines can result in users missing information. Consider that just because there’s a lot of space in the browser doesn’t mean you should fill all of it with text. Adding generous margins significantly enhances readability. GitHub does this well; their documentation is structured with short paragraphs, code samples, headings, and bold text, making it much more readable. Additionally, they incorporate step numbers in their headings, which helps users keep track of where they are in the documentation.
00:08:50.720
Heroku's documentation is effective as they place a table of contents at the top, ensuring users see vital information early on. However, there’s room for improvement. When presenting crucial terms, such as 'git' or 'gem file', using those terms at the beginning of the line can better catch users’ attention. Additionally, many users struggle with searching content; as Google improves, users mistakenly believe that if they can't find an answer, it simply doesn't exist. This stubbornness can lead to a frustrating experience, which is why it’s essential to consider how users search for information.
00:10:43.440
Jeff Atwood, one of the founders of Stack Overflow, emphasized that search terms are often varied. Users may pose the same query using different words, and having comprehensive answers allows users to navigate based on their terminology. For instance, at Twilio, we refer to library bindings in PHP, Python, and Ruby as 'helper libraries,' but users might search using varied language terms. We make the necessary adjustments in our documentation to address these discrepancies.
00:12:10.720
The implications of poor documentation can manifest in various ways, including an increased number of support queries. When users cannot find answers, they will reach out, leading to higher costs for companies, especially for open-source developers with limited availability. If users experience frustrations that lead them to abandon your product, that represents lost revenue.
00:12:51.680
Developing a model of the disconnect between writers and readers is crucial. Clay Christensen, a professor at Harvard Business School, offers insights through his 'Jobs to Be Done' theory. Instead of creating a product and identifying potential markets, he suggests examining how people use products and what needs those products fulfill. This perspective can greatly improve documentation by focusing on actual user needs rather than a one-size-fits-all approach.
00:14:34.560
For instance, when individuals purchase a Twilio number for call forwarding, they typically want a simple solution with minimal technical hassle. Historically, our documentation focused on broader functionalities, which did not cater to this particular use case well. Implementing straightforward links and offering tools to simplify tasks could enhance user experiences. Likewise, recognize that users do not start at the first page of a lengthy document; they scan for solutions and may miss vital instructions.
00:16:10.640
Assume users will engage with code snippets in isolation; therefore, provide context around those snippets. Often, poorly constructed code examples create significant frustration. For example, if a Ruby snippet fails to include necessary environment variables or documentation is filled with typos, this can bewilder users attempting to implement code. Maintain simplicity and transparency, ensuring that users can work through challenges without unnecessary obstacles along the way.
00:17:12.080
As a writer, it’s essential to consider the user’s journey and provide solutions as part of your documentation efforts. If users encounter an error, it’s beneficial to offer direct solutions frequently faced by users. This not only improves their experience but ultimately reduces future support inquiries.
00:18:43.440
The ultimate goal of documentation should be to preemptively alleviate user frustrations and guide them positively. Establishing clear communication pathways from error messages to documentation makes a significant impact. For example, giving detailed explanations of error messages and offering potential solutions shows users that the system is designed with their needs in mind.
00:20:00.000
Another example of effective error handling occurs in RVM, where installation processes are streamlined to avoid common obstacles faced by new users. This alleviates confusion and promotes a smoother initial interaction with the product.
00:20:38.640
Documentation should encompass insights into common user errors. By capturing both error messages and contextual guidance, you preserve clarity that can drive successful user experiences. Implement validation directly into your system, if possible, and offer users clear instructions to keep them on track.
00:21:30.400
It's essential to maintain vigilance over what users say when navigating your product. Observational activities like user testing can reveal distinct areas where users encounter struggles. Engage with real users and learn from their challenges. A simple request for assistance with your product can unfold a wealth of insights about user experience.
00:23:10.960
To summarize today’s insights, the first takeaway is to enhance readability in documentation. Utilize formatting techniques afforded by HTML, such as headings, bold text, and proper paragraph breaks. Ensure your writing style includes robust openings in your paragraphs—reminiscent of how BBC News structures its articles—for maximum impact.
00:24:36.000
Additionally, care about SEO as users frequently employ Google to find information. Craft your URLs and headings in a way that benefits their searches. Lastly, keep in mind that every page functions as a landing page; users may enter your documentation at any given point. Therefore, make sure each page conveys the necessary context.
00:25:55.680
Incorporate the 'Jobs to Be Done' framework to assess user needs on a granular level. Control the user experience throughout; even if interaction occurs outside your website, you can steer users effectively. Even if you're not technical, documentation writing can introduce a wealth of opportunities.
00:27:56.640
Eliminate user pitfalls before they happen, offering robust solutions through your documentation. Being proactive fosters a climate of user support and enhances overall satisfaction with your product.
00:28:48.239
Thank you for your time! If there are any questions, I’d be happy to address them. I appreciate your attendance and encourage you to engage in the happy hour events available.
00:30:09.440
Thanks again for coming!
