TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Re: Getting that info From:"William Sherman" <bsherman77 -at- embarqmail -dot- com> To:<techwr-l -at- lists -dot- techwr-l -dot- com> Date:Sun, 3 Mar 2013 23:53:02 -0500
I understand the error message foot dragging. Many times the designer doesn't know. And I will accept an "I don't know" as a legitimate answer, especially if they say, "I'll check on it" or "I'll find out what it does." After all, you can't know everything, and sometimes it is something you really didn't do, existing in a previous version or coming in as part of a change from elsewhere.
They put a fail point to pop an error code, but have no idea what may actually trigger that fail point. It could be a bad chip to a poor connection of a board. In many cases, the service rep or the field rep is often much more valuable in this information than the designer.
Other times, the designer is on a level that general questions don't work. I might start with the "2 minute overview of what this does" when first meeting, such as "this system processes all video information from command center, pilot's view, gunner's view, FLIR view, 3D view, and radar view as obtained from each of those subsystems." Then my next question may be a few days later after I have studied each of those subsystems. After all, being a TECHNICAL writer means I should learn and understand the technical aspects, not just write what some person told me to write.
Say I am working on a software book on an application. I get a copy of that application and run it. I run it the way the programmer/designer may have told me to, according to any existing procedures that may existed on it previous versions, or anything I have derived from the team.
Then I try it the way I think the bad customer would do. Ignore steps, skip steps, and just ignore the procedure and follow the GUI alone, as those "too smart to need documentation" would do.
I also intentionally try wrong things, see if it will break. For example, say you are supposed to enter a value 1 to 9. What happens with 19, 99, 11, or some negative number like -5, -11, and so on? Then I have specifics to ask.
"Hey, when I enter 11, which would be an easy mistake of bouncing the 1, I get this. Is this right? Is this anticipated? What happens if the customer uses 11 when the range is 1 to 9? Should this be blocked in code from happening?"
I usually ask very specific questions. I avoid the "tell me everything this item does" type of questions because first, it would take too long, and second, they are not there to educate me (you) on the product. I don't believe in sitting back taking dictation. I think it waters down the profession. I did a flight simulator a few years back. I logged lab time and put in about 50 hours of flying it, so that I knew what each control did and what to expect, got my screen shots at that time, and learned what it was expected to do and what was beyond those expectations.
Another writer on another simulator on that same team never put one hour in the seat. He chased designers every few days.
Now granted I couldn't have logged that lab time telecommuting, but there could have been ways around that, such as go on-site for 2 or 3 days occasionally and log time, or used an emulator.
----- Original Message -----
From: Editor in Chief
To: William Sherman
Cc: techwr-l -at- lists -dot- techwr-l -dot- com >> TECHWR-L
Sent: Sunday, March 03, 2013 1:33 AM
Subject: Getting that info (was Re: The Case Against Working at Home
On Fri, Mar 1, 2013 at 12:17 PM, William Sherman <bsherman77 -at- embarqmail -dot- com> wrote:
[...]
If I email someone for information on the Illudium PU-36 Space Modulator
revision that he designed, I should not have to chase him down a hall,
tackle him, and drag him hogtied back to his cube for me to get it. One
email request, and it should be on its way to me in a reasonable amount of
time.
[...]
Well, yeah, if you want a very specific piece of info, or three.
But things get a bit more grey (gray?) if you are looking for interpretation, background, or just info the engineer has, but nobody has ever asked him/her about it from the perspective that you introduced.
I do that. I usually get good, timely responses, but sometimes I get foot-dragging. It's really never that the SME is unwilling to provide the info, but it might be that he genuinely doesn't know how to do so. I find that further prompting DOES help, when I re-word, or try to tie the question more to the SME's perspective, or to the task he-or-she's been working on.
About a year ago, I had requests to add more info to a table of error codes and messages. It was like pulling teeth. The difficulty was that the people asking were field technical reps (support and pre-sales), and they were asking from the perspective of a customer using the system with their own (or third-party) applications. The engineer I was dealing with could tell you/me/anybody what each error code or message meant, in terms of what was going on inside the product. But what field people and customers were interested in were the situations in real life that might be represented by those codes.
What kind of situation or actions might some big application be involved in that could trigger this-or-that code or message? It was especially important to do that kind of mapping when the customer was using someone else's app, and therefore did not know which library calls and other actions were occurring - they just knew the macro situation and their inputs. My eventual solution was to get a strong field guy in a room with the SME. They happily bounced off each other for a couple of days, and some nice summaries emerged for the codes and cryptic messages. All I had to do was a bit of editing.
It wasn't arrogance that was the reason for initial foot-dragging, it was insecurity and puzzlement. The SME didn't have a good handle on where to start. Once he was talking to a kindred soul with related skills and plenty of experience on the customer side, he was pleased to participate.
My experience is that most people are glad, proud, to feel useful. Either I use my own skills to create the right environment for them to do so, or I find somebody who can help.
Generally, I can't say enough good things about our tech-support guys and our Sales-Eng people. For all kinds of reasons, the above being just one.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
EPUB Webinar: Join STC Vice President Nicky Bleiel as she discusses tips for creating EPUB, the file format used for e-readers, tablets, smartphones, and more.
