I’m always thinking about new ways to create clear and compelling content that can help my readers better understand the whys and how-tos of a feature. To enhance the user experience and usability of the content I create, I’ve been playing around for a while with the concept of interactivity.

The idea is to prompt users for some input (either a direct question or a selection they have to make from a list) to learn more about their configuration and provide them with customized content that meets their needs.

Pros

Adding interactivity to your content has many advantages:

• The readers’ engagement and, consequently, their level of attention increases. They are actively involved in the creation process of customized documentation.
• The amount of information displayed is significantly narrowed.
• The layout gets more interesting (dynamic content is here to stay)
• You’ll have happy readers if you can spare them from endless scrolling and dozens of clicks. I am also a frequent user of technical documentation and I know pretty well the feeling of being looking for a needle in a haystack…

Cons Challenges

There are not so many downsides (at least for the reader). I would rather reframe this thought by calling it “challenges”.

• Your readers will welcome this new approach but, as a technical writer, you will have to roll up your sleeves and learn some code. I realized long ago that, in order to become a better technical writer, you should be able to read and write code (which is tough but also very rewarding. To me, as a polyglot and language lover, programming languages are simply different types of languages, without “exceptions” in their rules).
• Depending on the type of interactivity, there might be some accessibility issues you might want to test first.
• JavaScript is widely supported, but again, there might be some exceptions you want to test. There are many approaches you can take to make sure that your content will be properly displayed (for example, by using cross-browser compliant libraries)

Example: Using Interactivity for Decision Trees

To be honest, this whole idea of creating interactive content came up after a long struggle with one of the topics I authored, which includes 7 different scenarios with dozens of conditions that the user has to take into account to reach the outcome that applies to a certain system configuration. I was obsessed to find a solution that could make this decision process easier for my readers.

This is one of the decision trees I created in the past as an attempt to move away from plain text and streamline the decision process:

(Note: the documentation I create is public. I accessed this site on Saturday, the 6th of June 2020. I would never disclose any confidential information here or anywhere else).

So, after putting a lot of thought into it under the shower, while jogging and sometimes even while sleeping (I’m not exaggerating) something suddenly clicked: Why don’t we ask the readers directly how their system configuration looks like and provide them only with the information they need?

Next, I googled how to create interactive decision trees:

As we publish our content as HTML, I selected this option and started to try out different options. Long story short, I came across this script that served my purpose: https://stackoverflow.com/questions/32591994/html-based-troubleshooting-decision-tree

I created a new Fiddle based on this one and customize it a little bit. This is the result: https://jsfiddle.net/marinahgtech/qs07t2La/30/ (note that this is just a sample. The whole tree is not coded. But you can see the interactivity and get the idea of how to implement this approach).

I will keep testing different options to move forward with this approach. I know this is the way to go in the future.