RE: What should an introductory seminar on tech writing cover?

[CBamber -at- castek -dot- com]

Neha Sharad wrote:

>One important topic that is hard to find in tech writing courses and
>seminars is how to interview engineers.  How do you effectively extract
>information? What are the right questions? What other methods can you use
to
>gather information (e.g., reviewing requirement and design documents; or
>sitting with the software yourself, if it's ready)?
>
>snip
>
>As a matter of discussion, here are a few essential questions a tech
writer
>might ask developers or engineers:
>
>--What's the purpose of the software? What's the business process it
>supports? (note: engineers may or may not clearly know how program ties
into
>the business)
>--Who's going to use it? What are we assuming the user already knows about

>computers?  About the business?
>--What platform/s does the app run on?
>--What was the program written in - Visual C, PowerBuilder, Pl1, etc.?
>--Do we have an inventory of all windows/dialogs, and their GUI objects
>already compiled? (If not, you as the tech writer compile one).
>--What error messages might a user receive? How do they resolve these? How

>is the resolution communicated to users?

I agree that info gathering needs to be taught - including how to interview
engineers. We consider it a core skill for techwriters and have to train
people to do  it in house.

I disagree that the questions above are effective interview questions. I
think they are much too general, and too basic. At my company, the
engineers (developers) would be courteous, helpful and give good answers
(because they are super people and extraordinary professionals) - and
they'd think the writers were a bunch of twits who hadn't done their
homework.

I consider the above questions orientation questions - you need to know
these things as background (what is it, what is it for, what resources are
available) so you can do the research you need to do to figure out what
questions you need to ask. You ask these questions of the PM or whoever you
report to just to put the project into context.

So what kind of questions are appropriate? It depends on your organization.
I think though, that before you ask questions you have to make use of every
inanimate resource available to you: in other words, if there are designs
or specs, read and assimilate the information in them; if there is software
to look at it - look at it and figure out what it does; if code is
available, look at it and at least read the comments; if data models
exists, look at them; if there are use cases and or process models, look at
them. Once you have assimilated everything there is, you should be in a
position to create a table of contents for whatever it is you are supposed
to be writing, and to figure out what info you have and what info you still
need.

Once you know what info you still need - then you can start thinking about
the specific questions to ask that will give you that info, and who the
best person is to ask. For example, if you need to know what the VIN field
is for on a window that allows a user to enter vehicle information, you
probably need to talk to a business analyst or user SME. If you need to
understand the rules that are being used to determine whether a
user-entered date is valid, you probably need to talk to a developer.

I do think that good questions have some common characteristics:

they are specific
you ask them in a context
they come out of your research

I don't know if this is helpful.

I would be glad to share info about our interviewing workshop if anyone is
interested (it's mine, rather than the company's - although I do give it
here). Send me a note offline.

Candace

------------------Putting the Future Together-----------------------
Candace Bamber
Castek
cbamber -at- castek -dot- com