tekom - Europe

Upcoming Webinars

Have a look at our webinar schedule for the upcoming months.

Product overviews vs. getting started tutorials - striking a balance between read-first and try-first user behaviors

Tom Johnson


This presentation focuses on balancing action with narration: How to find the right balance between action-oriented task writing and big picture narrative product overviews — both of which seem to be opposing but complementary content types in technical communication. 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 technical 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)?


starting time
26/07/21 | 16:00 clock
ending time
26/07/21 | 17:00 clock
Time zone
tekom Israel
Registration available only to logged-in members.

learning objectives

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.


Tom Johnson

Tom Johnson

Tom Johnson is a senior technical writer for Google in Seattle, Washington. He is best known for his blog, idratherbewriting.com, which has one of the largest followings in the tech comm community. Tom has also created an extensive online API documentation course (idratherbewriting.com/learnapidoc) that has helped hundreds of technical writers transition into API documentation.