Technical Writing and Keeping Readers Engaged

Jason

Ideas bounce around in my head
Super Member
Registered
Joined
Oct 26, 2016
Messages
6,011
Reaction score
1,036
Location
Nashville, TN
As a technical instructor in the field of telecommunications, my target audience during instruction is often adult learners, and while the courses often start with a bit of old school style lectures, we quickly get into hands on exercises during the week because that is how they learn best. I am starting to notice a trend whereby nearly everyone starts getting tripped up throughout the lab exercises. It takes me running around the room to 24 different work stations and walking through the exercise with each of them, and, yanno....reading the instructions to them! On each lab exercise!!

To prove this out, on the last day, I added a blurb at the top of the day 5 quiz that said:

"Please read all the instructions carefully before beginning these exercises. You need to read the instructions carefully because there is a lot that we covered this week. The world of telephony is filled with acronyms and there is no reasonable way anyone could expect you to memorize or remember everything we talked about this week. So, do not complete any of the quiz questions individually as we will work through them as a class. So, put my name at the top of this page, but do nothing else until we begin as a class. When you finish these instructions, don't forget to put my name at the top of the page."

I then told the students they would have five minutes to complete the quiz - but not to panic or stress because it's not a graded quiz, it's just to kind of gauge how much they picked up over the week. Nothing would be reported anywhere, this was just for internal training development purposes, and to please not rush through it and make sure to read the instructions. Then, I said,

GO!

They all flipped over the page, saw a list of about 50 acronyms in telecommunications and a blank spot next to each, presumed that they had to spell out the acronyms, and started filling it in. Except one student....

I walk back to his desk, and he had his name on the top of the page (habit), then a line through it and my name in its place. He smiled knowingly and leaned back. At the 60 second mark, everyone is still writing furiously. Continuing to walk around the room, most are trying to get as many acronyms down as possible.

At the 2 minute mark, I call out - 1 minute left! (My point had already been made, even though the reveal hadn't happened yet)...Nearly everyone is getting to the bottom of the page anyway, so finally, at the 150 second mark (2:30 seconds in), I called time. A few whispered curses from those who didn't finish. I then had the student at Position 1 (each work station is numbered incrementally) read the first sentence of the instructions out loud. I heard a curse...

The second student read the next line out loud. Then a few more curses.

By the time we finished, everyone was cringing at their total failure to read the instructions! It was quite enlightening for everyone, and we all had a good laugh over it. I sent the quiz off to my team, and said that every single student but one failed. My boss replied 5 minutes later and said he got all but one of the questions right without looking it up.

I replied back and told my boss he failed too: read the instructions!

Of course this has created an idea in my head about writing technical training materials as it seems techie types (myself included), tend not to read instructions all that well...how do you create technical content that keeps readers engaged?
 

Lakey

professional dilettante
Staff member
Super Moderator
Super Member
Registered
Joined
Apr 20, 2017
Messages
2,714
Reaction score
3,967
Location
New England
[/B]Of course this has created an idea in my head about writing technical training materials as it seems techie types (myself included), tend not to read instructions all that well...how do you create technical content that keeps readers engaged?

I am a technical writer too. I write documentation content for mathematical modeling, simulation, and analysis software used by engineers. My readers are engineers trying to figure out how to use our software to solve engineering problems. So I don't worry so much about how to keep them engaged as how to get them quickly on the right information trail toward the answers they need to solve their problems.

I know they aren't going to read instructions before jumping in and banging on the software. I know they aren't going to read a lot of text, or navigate through my carefully-organized category structure. They are going to drop in via search and scan the page they land on for terms that look relevant to them.

So I have to anticipate where they are going to run into problems, and anticipate what questions they are going to ask when they hit those problems. Then I have to try to get the right content in front of them at the right time, and make it so that they recognize it's the right content, by labeling it with terms that align with the way they are thinking about their problems. (For instance, "How to optimize the design of a fribble-wibble" rather than "How to use the Fribulator-9000 advanced mode".) When all of that is done well, they have a smooth experience that makes them feel our software is straightforward to learn and use. They might not even perceive it as, our documentation is really clear and helpful (though often they do).

To circle back to your question, then, for me as a technical writer, the problem is not so much writing content that's interesting and lively enough that my readers are encouraged to pay attention, but rather anticipating that they aren't going to want to invest a lot of time reading my content, and therefore designing my content to make it as useful as possible with as little investment of attention as possible. To make an analogy to your exam, it would be very bad for my users if I gave them a document that at first glance made it look like they needed to launch into a 50-step procedure, prefaced by a dense paragraph of text explaining that actually they probably don't have to do the procedure and can really just do this one thing instead. It makes a good point to teach people who aren't used to how users actually use technical content, but it would not be productive to mislead my users that way, by burying key information in text that I know (from experience and user-testing) many of my users are not likely to read carefully.
 

Siri Kirpal

Swan in Process
Kind Benefactor
Super Member
Registered
Joined
Sep 20, 2011
Messages
8,943
Reaction score
3,151
Location
In God I dwell, especially in Eugene OR
Sat Nam! (literally "Truth Name"--a Sikh greeting)

Jason, my 6th grade teacher back during the last ice age gave us a similar test. I failed it. Giving them that test was probably the best thing you could do to get them to read the instructions.

I've written how-to and I included little stories before and after the instructions. Seems to help.

Blessings,

Siri Kirpal
 

Jason

Ideas bounce around in my head
Super Member
Registered
Joined
Oct 26, 2016
Messages
6,011
Reaction score
1,036
Location
Nashville, TN
... It makes a good point to teach people who aren't used to how users actually use technical content, but it would not be productive to mislead my users that way, by burying key information in text that I know (from experience and user-testing) many of my users are not likely to read carefully.

Good point, and thanks for bringing these insights to the table. I should have probably been clearer that the technical writing I am speaking to is updating the lab guides so that the students are more engaged. So, this isn't targeting users of software per se, it's more in an educational setting.

Sat Nam! (literally "Truth Name"--a Sikh greeting)

Jason, my 6th grade teacher back during the last ice age gave us a similar test. I failed it. Giving them that test was probably the best thing you could do to get them to read the instructions.

I've written how-to and I included little stories before and after the instructions. Seems to help.

Blessings,

Siri Kirpal

Thanks - I actually like the idea of giving a pre-assessment evaluation before the course, and have mentioned it to the pay grades above my own, but no one has listened yet. I personally think a pre and post class test would be most informative as to who actually learns anything, but I digress...

The idea of delivering this "quiz" before the labs is genius! I will do so for my next class and see how it goes with student engagement on the lab exercises! :)
 

AW Admin

Administrator
Super Member
Registered
Joined
Apr 19, 2008
Messages
18,772
Reaction score
6,285
Anytime you're giving instructions or important information to anyone, whether it's documentation, facts, or recipes—use white space.

Use bullets and numbers where appropriate.

Remove words you don't need, especially hesitation markers.
 

Jason

Ideas bounce around in my head
Super Member
Registered
Joined
Oct 26, 2016
Messages
6,011
Reaction score
1,036
Location
Nashville, TN
Hmmm...y'all are making me think - the prior creator of these lab guides tends to think of them as their "baby" and has thus far not been too receptive to changes, but if I can get my hands on them and make some updates along these lines, it may drive better engagement from the classes. I'd love to submit one of these guides under SYW, but they're very heavy with screen captures and probably wouldn't work well under the forum parameters.

Love the white space suggestion, thanks Lisa! :)
 

Chris P

Likes metaphors mixed, not stirred
Kind Benefactor
Super Member
Registered
Joined
Nov 4, 2009
Messages
22,617
Reaction score
7,298
Location
Wash., D.C. area
Oh, you're one of THOSE instructors! *grumbles and wants to email your students in sympathy*

That said, it was a great exercise and proves your point. Your evil ingenuity is beautiful. I've had to write many emails starting with "I'm sorry I didn't at first notice where you mentioned . . ." To echo Lakey, even though it's a good lesson to the students in reading and following directions, it's just as important for the assigner to provide tasks that are as self-evident as possible and anticipate what the recipient expects so the task can be done right the first time with minimal preparation. But a good lesson in not jumping ahead never hurts.
 

Jason

Ideas bounce around in my head
Super Member
Registered
Joined
Oct 26, 2016
Messages
6,011
Reaction score
1,036
Location
Nashville, TN
Adding to Lisa's point from another thread vis a vis giving context, here's the backdrop of my situation:

My boss means well, and the fact that he created the lab guides and PPT decks with his limited foray into teaching methodologies is a testament to his ability to transcribe his knowledge into a coherent form. But the problem is that not everyone learns well from reading, or being read to (which is how the PPT and lab guides are written).

So, I am kind of stuck between a rock and a hard place - a boss that wants me to get more into curriculum development, but doesn't wanna let his baby slip away from him. At the end of the day, I improvise for classes, blending the best of what the PPTs and lab guides offer with my own tangential deviations to help give it context for the modern learner.

Classes also are never the same way twice because if it seems after the first day that everyone is operating at a higher level, I ditch the PPT's almost entirely and start breaking the soft switch then have them collectively troubleshoot it as a group while I act more as a guide or a "moderator" so to speak.

Alternatively, if some are new to telephony entirely, then a bit of lecture is needed to set the stage for what the differences are between TDM world and the VOIP world and how they blend together.

We almost never "stick to the script" which kind of bugs my boss, but the student reviews and evaluations speak for themselves, so he lets me keep at it in my own way. :)

Now, if I could just get ownership of the PPT and lab guides! LOL
 

Layla Nahar

Seashell Seller
Super Member
Registered
Joined
Feb 6, 2007
Messages
7,655
Reaction score
913
Location
Seashore
My readers are engineers trying to figure out how to use our software to solve engineering problems. So I don't worry so much about how to keep them engaged as how to get them quickly on the right information trail toward the answers they need to solve their problems.

I like this approach. I try to think in terms of what is the quickest way readers can get the information they want.
 

Lakey

professional dilettante
Staff member
Super Moderator
Super Member
Registered
Joined
Apr 20, 2017
Messages
2,714
Reaction score
3,967
Location
New England
Good point, and thanks for bringing these insights to the table. I should have probably been clearer that the technical writing I am speaking to is updating the lab guides so that the students are more engaged. So, this isn't targeting users of software per se, it's more in an educational setting.

There are some differences between your audiences and mine, for sure. But even in your lab guides, the purpose of them is to get the students doing the exercises. And the reason one inserts exercises into courses for adult learners is that study after study shows that active learning is more interesting and retained better than passive learning.

So just like my documentation, your lab guides need to get your students doing things, as quickly as possible, and with as little extraneous information as possible. If you're making them read through so much background that they are skipping it to get to the action, then think about whether that background is really needed to do the exercise and learn from it. And if it is, try to think of ways to deliver that information in a more just-in-time way, to get them to the action quicker. If there's a piece of information they won't need to use until step 3, you can wait until step 3 to give it to them.

You are in a tough situation if your boss is reluctant to let you revise the lab guides - I get that. I love that you're thinking about it (and I love jabbering about the theory and philosophy of information design), but I do recognize the reality that limits you. Good luck with it!
 

Kalyke

Super Member
Registered
Joined
May 7, 2008
Messages
1,850
Reaction score
182
Location
New Mexico, USA
I have an M.Ed, and have been to "teaching college." The instructions would have been considered a "trick," or "trap," and highly discouraged. Do you want these students to disbelieve everything you say? Also learning is not about obeying, or disobeying orders... well, maybe in the military. My wonderful Ph.D. Professor who taught advanced math at Embry-Riddle told me once, "never trick your students."

When teaching, you have to make the students actually trust, and believe you. One little move and you lose them, and then, where are you? Think of it in terms of Pavlovian conditioning. That is where the dog would get food with one action, and get shocked with another. Your students just got "shocked," in metaphorical terms. If they are not 50 and did not grow up during the 70's they are gen-Y or Millennials they are used to taking mindless tests and assessments (thanks to the public school system). You open a folder with 50 questions, and someone says "start," it is like yelling "fire" in a theater.

My BA was in "Professional Writing." I liked writing feature articles.
 
Last edited: