December 3, 2008

Asking Questions is Key

I think one of the hardest things in technical writing, especially for new hires, is to be assigned to document a product or feature that you know nothing about. Since we have a wide variety of LabVIEW products, from signal processing to HMI to control and simulation to report generation to sound and vibration measurements (not to mention the core product itself), no one can be expected to understand the minutiae of them all. And yet our writer who works on a Control Design product might be asked to edit another writer who is working for an HMI product. Or the signal processing writer might leave and the HMI writer might be asked to fill in until we can find a replacement.

Whew. That's a lot of stuff to cover. But we're not engineers. Some of us have a technical/mathematical/scientific background, sure, but many of us are English or Tech Comm majors. How do you write help for a product you know nothing about?

Well the answer is: you learn. You do this primarily by working with Subject Matter Experts (SMEs) who, here, are the engineers who develop these products. They are the ones who have not only the domain expertise (like advanced degrees in the aforementioned disciplines), but also the LabVIEW programming knowledge to help you write documentation.

Still, it can be daunting to read a feature spec and not know where to begin. That's why I believe one of the most important skills a technical writer can have is knowing how to ask questions. (There's a reason we have several Journalism majors who work here.) Questions about functionality, background reasoning, implementation, usefulness, future features, and so on. Questions that nitpick and dig into what the developer really meant when he said "if necessary". These are all fair game in determining a starting point, an outline, for writing documentation. And once you have that outline, you're in far better shape than you were before, because you have a plan of attack. Even if you initially knew nothing about the feature.

Of course, it's a chicken-and-egg problem. You can't ask questions if you don't know enough about the feature to know what questions to ask! That's why, on the LV Doc team, we've developed a list of questions to help writers, especially new ones, get started writing about unfamiliar features. That's why research with the developers can be so valuable. Even if you don't know what they're talking about, you can pick out patterns, keywords, and things to ask questions about later.

That's why we look for writers who are geeks, who love learning technical information. We don't ask you to be a computer scientist when you join NI. But if you're going to write for (as an example) LabVIEW, you'd better get a thrill out of learning about object-oriented programming, data types, and 3D graphs. Otherwise you're going to hate it here, which is a situation nobody wants :-)

Over time you develop patterns of behavior that proves successful in giving you a sufficient amount of information about a product in a short amount of time. And then when you're asked to pitch in on another product, you aren't afraid anymore. You trust yourself to be able to obtain the knowledge you need in order to do your job well.

7 comments:

  1. Great post.
    As a journalist who works for an industrial tech. magazine, often I find myself interviewing engineers about new products and technologies I've never heard before.
    When I started out, I was ashamed because I didn't understand or even pronounce right the acronyms, but I had to understand I was a journalist (without any specific training in this area but with ever growing interest and passion) and went to my interviews with a humble attitude, starting with the most basic questions... And most people were pretty nice about it, too...
    Nowadays, time and experience have certainly augmented my knowledge in the area, but still I'm not an engineer... So, I have a bunch of questions that allows me to try to grasp the concepts involved with the product, such as:
    - New features of the product: Why are they important?
    - Benefits for the users: How do they benefit from using the product o the new features?
    - Is this an evolution o a revolution?
    - What are the key differences with similar products available in the marketplace...
    You get the idea...
    Cheers...
    Marcelo A. Ortiz

    ReplyDelete