A technical communicator’s history lessonJanuary 28, 2011
Last week, Tom Johnson posted twice about how users read (Less Text, Please and Making Help Content Enjoyable to Read – Impossible Quest?) The blog posts and resulting conversation that took place via the Comments proved the argument that people read differently according to their goal.
This got me thinking.
At first, I skimmed the posts, believing that we’re already addressing this by organizing content according to audience roles – for example, offering an Administrator’s Guide in addition to an End User’s Guide, because the two roles use the software differently. But as I read more deeply – and this is a point I will revisit later – I realized that “use” of content shouldn’t be confined to job role. Within and across job roles, users read for different purposes – Doing, Learning, or Learning to Do. (Read the posts for more information on these concepts, as well as their sources.)
This reminded me of my first job back in my early twenties. Between 1987 and 1993, I was a secretary at a large commerical bakery whose products are sold in grocery stores. Managing the bakery’s large fleet of delivery trucks required access to data like mileage, fuel consumption, maintenance history, parts usage, and accident reports. The fleet was geographically distributed over most of the northeast so collecting and analyzing all of this data would have taken weeks if we hadn’t been able to computerize it.
Back then, we didn’t have Windows or email. There wasn’t even an Internet yet, not as we know it. We used a network of PCs running an operating system you probably never heard of: B.O.S. Business Operating Systems. It was ugly; no fancy GUI screens, just old fashioned Green Screen. Everything was command-driven. All these years later, all I remember is the $ prompt. $A, $F, $S. I had a list of these $ commands typed in a single skinny column taped to my monitor.
My first Quick Reference Guide. (grin)
As I noted in my comment on Tom’s blog, I was asked to produce a monthly report from this system. There was a report generator called Auto Clerk that could produce reports from the database. I was handed an Auto Clerk guide, a Command Reference Guide, and a third guide whose name I can no longer remember that was mostly concepts and explanations.
I had a goal in mind – produce a report. That’s all I knew. In other words, I did not know what I did not know to achieve my goal. The index and table of contents contained technical terms so I could not look up anything unless I first “spoke the language.”
That must be what the unnamed third guide was for. I read it cover to cover. I learned how long BOS existed, how it worked, what technologies it was based on. I finally found a very high-level description of the report generation process. That sent me to the Auto Clerk guide.
Again, I had to read the entire book cover to cover simply to learn what the right terms were in order to achieve my goal. What $ command instructs the system to first query the database and then display or print the results of my report design.
Wait. What report design?
Okay. Back to formula. I then focused on finding the commands to design a report. First, column layout, then the fields in the database whose values would provide the rows of the report.
That brought me to the last book, the micro-COBOL command reference guide where I had to find the commands and the syntax that would produce the output I wanted.
This took me almost two months to do. Granted, that was in addition to my usual responsibilities but still, two months of research? After two minutes of clicking links, I am now frustrated.
When I finally got a report out of that system, I typed up the entire procedure in my own words. I didn’t know it then, but that was my first piece of true technical communication.
What have I learned from this?
- BOS assumed I was reading to learn. I was not. I was reading to do.
- BOS presumed I already possessed a certain level of technical proficiency. I didn’t. I hadn’t yet finished my college degrees. However, I can tell you this – producing the report did NOT require all that domain knowledge.
- The Table of Contents and Index were not designed to help me find information; they were designed to browse for information. In other words, you must already know what you’re looking for.
- The guides were missing any real, specific examples, expressed as a typical user need. I had to cobble together syntax examples provided at the bottom of each command description in order to string together the combination of results I needed. The challenge with this is the technical writers used < > to denote user-specified values. I had a devil of a time determining when to omit those brackets in my own commands and when they were required.
How Would I Have Done This Today?
So much has changed since my days dealing with BOS. I would speak English instead of COBOL or whatever geek-speak a subject requires. For example, instead of writing a heading like “$F Command – Report Generation” – a heading that told me nothing about its contents, I would have written, “Design Your Report’s Layout”, “Specify the Data to Use in Your Report” and “Display or Print Your Report.”
Adobe similarly frustrated me with headings like “Use the Dodge/Burn Tool.” That would be great if I already knew what dodge and burn mean.
In the Index, I would enter such a topic in English, for those who don’t yet have the domain knowledge, and in geek-speak, for those who know what they’re looking for.
I’d make use of hyper-text technology and demote all the high-level conceptual stuff that did not matter to me in my goal of producing a report to an exandable link in a Help system – there if I want it, not there if I don’t. Deep Reading, the kind of reading I do when I read a novel, for example, or study a textbook, requires the proper mind-set. I cannot put myself in Deep Reading mode when I know I have a conference call in fifteen minutes, two people are at my desk, and my Inbox has 400 unread messages.
I would organize the commands by purpose not alphabetically. The Index is already an alphabetized list. I’d provide tons of real-world problems with the exact syntax for solving each.
My shoulda/woulda/coulda list got me thinking. Am I doing all this today? Sort of. On one of my projects, I added a nice What Would You Like to Do Next section to most of my help topics, which achieves a few goals. First, it gives readers a sense of direction. “I’m here and want to go there.” Second, it conveys sequence. “I’ve done X and Y and still need to do Z.” It implies ordinance. “I’ve done X; now I can do Y.”
But I could do more. Sadly, I find so much of my ideals are sacrificed to the gods of project schedules and budgets.
So, that’s how Tom’s posts got me linking my past to my present. What do you do to address not just different audiences, but different ways of reading in your technical writing?