How to Write Documentation for People That Don't Read

by Kevin Burke

In the presentation titled "How to Write Documentation for People That Don't Read," Kevin Burke from Twilio addresses the challenges of creating effective documentation for users who tend to scan rather than read content thoroughly. He emphasizes the significance of understanding user behavior, specifically how they navigate products and seek answers. The following key points are highlighted throughout the presentation:

User Browsing Behavior: Most online users do not read word-for-word; instead, they scan for relevant information, leading to a significant challenge for documentation writers.
Research Insights: Burke references usability research by Jacob Nielsen, which reveals that users often follow an F-shaped pattern when scanning web pages, indicating areas of content that receive more attention.
Clarity and Brevity: Effective documentation should be clear and concise. Large blocks of text should be avoided, and information should be presented in a scannable format with appropriate headings and bullet points.
Visual Formatting: Using effective formatting techniques—such as bold text, short paragraphs, and generous whitespaces—can help emphasize key information and improve readability.
User Experience Examples: Burke critiques specific examples of poor documentation, such as GitHub's unformatted README files and Twilio's problematic banners, illustrating how structured layouts can enhance user interaction.
Search and Accessibility: Users often search using varied terminology, so documentation should incorporate common search terms and clear navigation to ensure users can easily find what they need.
Error Handling: Documentation should preemptively address potential user errors by providing clear solutions alongside error messages, thereby enhancing the user experience.
Jobs to Be Done Theory: By considering how users actually use products and the needs they fulfill, documentation can be better tailored to meet real-world scenarios, improving user satisfaction and reducing support inquiries.

Conclusions and Takeaways:
- Prioritize readability in documentation by utilizing formatting tools and being mindful of user scanning behaviors.
- Develop a keen understanding of user needs to create helpful, targeted content.
- Regularly engage with users through testing and feedback to identify documentation shortcomings and improve user support.
- Emphasize that documentation is crucial for user retention and reducing support costs, making it a vital part of product development.

Burke's insights underscore the importance of structuring documentation not just for completion but for user engagement, ensuring that even the busiest users can access the information they need efficiently.

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!