Stay updated
Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 5,800+ subscribers. (See email archive here.)

Search results

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

by Tom Johnson on Aug 7, 2021 •
categories: technical-writingpodcasts

I recently gave a webinar to tekom Europe about product overviews and getting started tutorials. The recording and slides are below.

If you remember, a few months ago I was brainstorming for this topic in a post titled Balancing action with narration: Creating product overviews and getting started tutorials to satisfy both try-first and read-first learning modes. This is the recording of that presentation.

Presentation description

Here’s the presentation title and description:

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

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)?

Presentation recording

Here’s the recording (my screen + voice only). If you’re a tekom member, you can view the full recording (intro + Q&A) from within tekom’s webinar archive.

You can learn more about tekom Europe here.

If you just want the audio, here it is:

Slides

Here are my slides:

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

Content pages

I also added two sections to my API course that provides a written version of the content:

Here are the new sections:

Thoughts

Overall, I liked this topic, but I don’t see myself giving multiple presentations on it. There’s something about presenting on content itself that is not as engaging as meta conversations around content. There’s no inherent shape to the material that drives it along as a story unto itself. I still think these two topics can be game-changers in documentation, but if I’m going to give multiple presentations on the same topic, I think something else might be more interesting.

(Also, as a disclaimer, it was early in the morning when I gave this presentation, and I wasn’t fully awake. With the early hour and the material being new, I wasn’t as articulate as usual. At times I thought about rerecording this, but ultimately I decided to post it as is. I did receive positive feedback on the webinar, so maybe I’m being too self-critical.)

Buy me a coffeeBuy me a coffee
Stay current with the latest in tech comm
Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 5,800+ subscribers. (See email archive here.)

follow us in feedly

About Tom Johnson

Tom Johnson

I'm a technical writer / API doc specialist based in the Seattle area. In this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, visual communication, information architecture, writing techniques, plain language, tech comm careers, and more. Check out simplifying complexity and API documentation for some deep dives into these topics. If you're a technical writer and want to keep on top of the latest trends in the field, be sure to subscribe to email updates. You can also learn more about me or contact me.

Comments