Re: Interviewing/getting info from SMEs

[Geoff Bradbury <bradg -at- INTEXT -dot- CPSG -dot- COM -dot- AU>]

Greetings...

My first suggestion, when dealing with software developers, is to get a whip
& chair! Seriously though, I'm the sole tech writer surrounded by 17
software engineers/designers split into product teams. I've had similiar
problems with over-zealous engineers adding new features without telling me.
A sort of "Gosh, that dialog wasn't there this morning!" syndrome.

Over time I've managed to instill a sense of communication into the product
managers. They put together a project plan that details the product, its
interface, user requirements, etc. Whenever a change is implemented, I
receive a copy of the change request from the project manager (the engineer
receives a copy of same). While a somewhat informal approach, it works well.
We all keep abreast of the product's evolution.

I always jump in at the earliest stages of product development. I make sure
I'm included in design meetings and definitely put in my $0.02 worth. With
this approach I get a very good feel for the features the product is to
support. The same applies when product upgrades are being planned.

From what you've written I'm a little surprised that you (& your team)
aren't involved in the design phases of your products. That's where we
communicators can truly act as user advocates: seeing the product through a
user's eyes (not an engineer's). It helps prevent plain dumb ideas & bad
interface design from ever seeing light of day.

Your new writer's astonishment is justified. Quite often the developers
won't have an idea (or often care) what's happening about your
documentation, much less their own documentation. I try to involve our
developers by 1) talking to them (using an informal interview technique);
and 2) passing them parts of publications to technically edit. If I'm having
trouble explaining a concept, or a feature is taking too many words to
explain I take it back to the responsible engineer for a possible rework.
They're learning that writing's _not_ the piece of cake they thought it was!

I'm not sure about having tech writers that aren't really tech writers. You
may discover some latent writing talents in your new staff. Good luck!

>I work for a relatively young software development company.  I was the
first tech writer on board, but now we are adding several more.  Only one
>of the new people will have specific tech writing experience, so I am
trying to get some procedures in place for them.

>One of the things that has really been a challenge is getting a system that
makes sure that we get all the information we need from the development
>staff.  Initially, the tech writers are just given pre-release versions of
the software, and we're supposed to just click around and figure out how
>it's supposed to work.  This is OK in the "getting your feet wet" stages,
but (not surprisingly!) we've come across more and more situations where
>we've almost missed features.  The development staff doesn't do much in
terms of upfront designing-often there are no plans or feature lists the
>tech writers can use as source documents.  Usually I catch this stuff
because I eat lunch with these folks, I eavesdrop a lot, and I am just
>plain nosy.  I can't count on all the new folks being as obnoxious as I am,
so I would like to have some sort of framework in place.  One of the new
>folks seems frankly astonished that the developers don't notify us each
time they make a change that affects the documentation; he also seems to
>think that we should be able to get stuff from the developers (written
stuff, not actual software) that spells most of this stuff out.

>How do you do this?  Do you get at least a feature list from the developers
to start with, and then just develop a list of questions from there?  Do
>you go ahead and try to figure out 90 percent of the system before you talk
to the developers, or do you expect them to be able to explain the system's
>basic concepts and everything to you?  What mechanisms do you have in place
for when they change their systems (either in the underneath, how-it-works
>part, or in the interface)?
IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII
IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII
Geoff Bradbury          InTEXT Systems         voice: +61 6 283 6804
Technical Writer        P.O. Box 7126            fax:   +61 6 285 4316
                               Canberra Mail Centre
                               A.C.T. 2610
                               Australia
IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII
IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII