07-09, 14:35–15:05 (US/Pacific), Room 317
User guides are the piece you often hit right after clicking the "Learn" or "Get Started" button in a package's documentation. They're responsible for onboarding new users, and providing a learning path through a package. Surprisingly, while pieces of documentation like the API Reference tend to be the same, the design of user guides tend to differ across packages.
In this talk, I'll discuss how to design an effective user guide for open source software. I'll explain how the guides for Polars, DuckDB, and FastAPI balance working end-to-end like a course, with being browsable like a reference.
In this talk, I'll draw on my work on user guides for tools like Great Tables and Shiny for Python--as well as some great guides for popular libraries--to explore 3 big focuses for guides:
- Onboarding: helping new users get started with your software.
- Diving deeper: ensuring users can learn to perform key tasks with your software.
- User guides in the wild: lessons learned from great user guides.
Onboarding
First, simplified whole tasks illustrate the big picture. Guiding users through the simplest, whole example of your tool helps them see the big pieces, and how they connect to each other. Second, backwards design lets users eat cake first. Rather than starting from the very first step and work forwards, starting from the end result often shows the most interesting part first.
Diving deeper
In this section, I'll look at how guides can help users take their next steps. First, domain models provide a conceptual backbone for documentation. By organizing guide pages around a diagram or conceptual workflow, users become better at navigating the guide as they learn your tool. Second, guide pages need to be sequenced to work like a course and a reference. Users should be able to read a guide from end-to-end, or come back and browse it to get help with specific topics.
User guides in the wild
In this section, I'll draw inspiration from three existing documentation sites. First, DuckDB provides examples up top at the very start of each page, with rules detailed below. These examples serve as a quick refresher for people who already have some experience with SQL. Second, FastAPI uses an incredible number of simple, complete examples throughout its guide. Finally, Polars balances teaching high-level concepts, like its lazy expressions, with diving deeper into specific topics.
Inspiration
Note that this talk was inspired by my work on quartodoc, a tool for generating API References. I noticed that while API References are often similar to each other, user guides often differ from package to package, and are hard to get right.
I'm a data science tool builder at Posit, where I work on open source tools for data analysis (like siuba).
Previously, I worked as a consultant building out a data team for Caltrans (and love all things GTFS).
I received a Ph.D. in Cognitive Psychology from Princeton University, and am interested in what drives expert data science performance. This led me to build DataCamp Signal, adaptive tests of data science skill.