Kayce Basques

A UI That Lets Readers Control How Much Information They See

Technical Writing

Parametric Press enables its readers to control how much information they see via a slider that has 4 options: "TL;DR", "Essentials", "Highlights", and "Everything". This post explores whether this feature would be useful in documentation. My initial impression is that the ROI does not justify the effort.

Last week, in our team chat, my colleague Houssein Djirdeh posted a GIF of a UI that enables readers to control how much information they see.

Try it out for yourself at Parametric Press .

Or, try it out on this blog post! Everything Mode shows all of my thoughts related to this feature. Essentials Mode shows just the most important information. Note that I put the non-essential Web development is a useful skill for technical writers section next in order to show how sections disappear when you enter Essentials Mode.

You are now in Everything Mode.

Web development is a useful skill for technical writers

If you're looking for skills to complement your technical writing, consider web development. Especially if you work in an industry that mostly publishes its documentation to the web.

Knowing how to build websites enables me to experiment with the UX of my docs sites, like I have done with this post. Having a working prototype of this feature enabled me to think much more deeply about how this feature might affect the authoring side of documentation.

I also think that we can bring meaningful innovation to technical writing by measuring how users interact with our docs sites in order to learn what they truly want, and experimenting with new ways to present information.


If you do implement this feature in your real documentation, for accessibility reasons it will be way safer to present the full page by default. Essentials Mode should be the opt-in choice. Your typical web developer is probably going to use the display:none CSS declaration to hide non-essential content. display:none makes content completely inaccessible to screen readers.

A strategy for catering to multiple audiences?

This might be a useful feature if your audience is split between beginners and experts. For example, suppose you got feedback from beginners that your tutorial didn't include enough context. So you add context. But then the complaints from the experts roll in. "Why are you making me sift through the basics? Just tell me what to do."

With Google Analytics Event Tracking it's possible to track how much aggregate time is spent in Everything Mode or Essentials Mode.

I'm doing it on this page, in fact. Click Get Stats to get the real analytics for this blog post, from the day that I published up until yesterday. Note that I'm effectively using Google Apps Script as my REST API server, so if the data doesn't load, I probably hit my quota.

Considering that Everything Mode is the default view, if the majority of readers on this post were viewing it in Essentials Mode, I'd take that as a pretty strong indicator that I've provided a lot of content that no one actually cares about.

Impact on authoring workflows

From my experience so far, adding this feature seems like it'll create a noticeable amount of extra work for writers. One way or another, you're going to have to mark up a lot of content. You'll also have to make sure that each mode of a given document flows well. For me, that meant reading the Everything Mode of this blog post, and then going back and re-reading the Essentials Mode.

Parametric Press provides 4 modes. If I did 4 modes in my docs, I'd get analysis paralysis. I can mostly handle classifying content as high-priority or low-priority, but 4 modes would be a mental burden. But even in this toy example, I found myself asking "is this section high-priority, or low?"

Prior work?

I'm pretty sure that other technical writers have tried this feature before. Perhaps DITA practitioners? Because DITA lends itself well to features like this.

If you're aware of any relevant case studies or research on this idea, please send me an email at kayce@basqu.es and I'll update this section.


Does the ROI justify the effort?

It depends on how strongly users respond to the feature, because it'll create a noticeable amount of work for writers.