Suggest modification to this talk

Title

Description

By Kevin Burke

Usability researchers have known for years that people browsing the Internet 
don't read things word by word - they scan pages for the content they want. Yet 
many API's and documentation resources are written as though users are reading 
every word. If busy users can't find what they are looking for, you'll have 
more support tickets (an expense), or more frustration (lost revenue).
Writing effective documentation requires knowing who your users are and how 
they are finding answers to their questions. In this presentation, we'll 
examine practical techniques to make your documentation work for busy users. 
Looking at examples and user testing from our experience at Twilio, attendees will learn:
- how users find (or fail to find) your documentation 
- how users view and get started (or fail to get started) with your product 
- how to take advantage of underused documentation tools like your error messages, your API, and SEO.

Help us caption & translate this video!

http://amara.org/v/FGai/

Date

Summarized using AI?

If this talk's summary was generated by AI, please check this box. A "Summarized using AI" badge will be displayed in the summary tab to indicate that the summary was generated using AI.

Show "Summarized using AI" badge on summary page

Summary

Markdown supported

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.

Cancel