A technical communicator’s history lesson

January 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.

Uh Oh

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?



  1. It’s an interesting subject. Doing, Reading, and Reading to learn. Fascinating really. Thanks for pointing this out. The concepts seem obvious, but they’re easy to overlook.

    In general, I’ve gone the route of offering tutorials for novices, and these focus more on the “Reading to Learn” part. But even then, the technology I work on is so specific, only the Operations Guides handle general audiences, and they still assume some knowledge.

    Anticipation of sticking points and user observation are probably the keys. But while I can anticipate well enough, getting novice users to test the project so I can observer them is a different issue. That almost never happens. Plus, frankly, I never get much time for it.

    Anyway, nice writeup. I enjoyed it.

  2. Thanks! Appreciate your comment. I think today’s web-based technologies makes it easier than ever to address all reading types in our work. When we were writing actual “books,” it was difficult to ensure we did enough to support novices and experts alike.

    But with hyperlinking, we can point novices to concepts, tutorials, and other content that provides the domain knowledge our advanced users already possess. I agree; we rarely have the time to do all this.

  3. I think when the writer determines which documents are appropriate for each product, it is possible to segregate the types of information into separate documents for each type of use. If your company provides only a limited set of user info, such as just user and administrator guides, the job is harder. The information in the user guide has to have a tutorial section to get the new users into using the product, with a typical work flow scenario, and then provide additional topics in an easy-to-find format with appropriate notes and tips to enable them to easily perform the application’s less frequently used functions, such as creating reports.

    The Administrator’s guide also requires instructions for entering the program (probably less tutorial than the user guide) and accessing all the functions and variables that the admin can change to configure or reconfigure the program for the users. This material needs to be presented with screen shots and tables of variable or options, so that the admin can easily recognize that s/he is in the right place in the application, and can make an informed choice of options or parameters to effect the desired changes in the configuration, the user access permissions, or whatever.

    Whether the information in in a paper document, a PDF, on online Help, I was taught to always try to give the users as many “handles” to find the information they need as possible. This includes detailed TOCs with informative headings and subheads, indexes, lists of figures and tables, descriptive table and figure captions, section identification in headers or footers, search options, etc. Everyone uses different ways of searching and scanning for that key piece of info they need to keep working, but they don’t want to waste any time doing it, so do everything possible in each document to help them out.

  4. You make an excellent point in your last paragraph: “Everyone uses different ways of searching and scanning for that key piece of info they need to keep working…”

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: