Balancing action with narration: Creating product overviews and getting started tutorials to satisfy both try-first and read-first learning modes
August 7, 2021 update: For a recording of this presentation, see Recording of Product overviews vs. getting started tutorials — striking a balance between read-first and try-first user behaviors.
Presentation title + description
Balancing action with narration: Creating product overviews and getting started tutorials to satisfy both try-first and read-first learning modes
Ideas such as minimalism (as defined by John Carroll, Hans Van Der Meij, and others) and research about opportunistic learning behaviors encourage much more action-oriented approaches to tech writing. These action-oriented approaches might include getting started tutorials, interactive features like Swagger UI, code you can run directly in the browser (e.g., Jupyter Notebooks), task-focused how-to’s, and more. For decades now, researchers have been reiterating the belief that users are “reading to do” and are anxious to get going with tasks and other hands-on exploration. Readers don’t want lengthy explanations but rather specific steps to accomplish a task at hand.
At the same time, documentation often fails to tell the who/what/when/why about the product. Anemic overview pages provide little detail about what the product even is before jumping directly into how to configure it and install it. Countless project overview pages on GitHub give almost no indication about what the project code actually does, nor list its use cases, target audience, or other high-level details. Many of the problems with documentation involve the absence of a larger story around the product, a lack of connecting pieces that tie all the components together into a cohesive arc.
How do you balance this tension between action (with task-based docs) and narration (with concept-based docs)? When do you focus on reading to do versus reading to understand?
In general, best practices for documentation would mean accounting for both mindsets and orientations. For the reading-to-do mindset, you provide a getting started tutorial that gets the reader going in an immediate, hands-on way with the product. For the reading-to-understand mindset, you provide a product overview that answers high-level questions about the product, including the problem it solves, who the product is for, sample use cases, architectural diagrams, development timelines, known limitations, and more.
In this presentation, I’ll provide best practices for writing both getting started tutorials and product overviews, with good and bad examples of each.
Additionally, I’ll explore ways that these two topic types can complement each other. Getting started tutorials can sprinkle in high-level concepts, finding teaching moments to illustrate concepts or features mentioned in product overviews. Similarly, product overviews can point to the getting started tutorial for more concrete information about the abstract concepts. The two topic types can be interwoven in ways that reinforce each learning type.
In general, the product overview and the getting started tutorial should work together to help instruct the user in a way that accommodates both the opportunistic (read to do, or try first) learner and the systematic (read to understand, or read-first) learner. The two can link to each other, reference each other, and support opportunities for each behavior to springboard into the other.
Your feedback
To collect your feedback, I created a short multiple choice survey here. You can see ongoing responses here.
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.