Re: Time with Engineers (was What We Do)

["Susan W. Gallagher" <sgallagher -at- STARBASECORP -dot- COM>]

Rose Norman writes...

[snip some background]

> So the question is this: how much time do you spend getting information from
> engineers (e.g., how many hours a week) in order to write and maintain a
> technical document?  Also, how do you get this information--on the phone, in
> writing, in regularly scheduled meetings, in casual office time?  etc.

So much of this varies with the type/complexity of the software,
but as a general rule, I spend very little time with the
engineers.

My job starts with the program's functional spec or prototype.
We usually get a demo or a working prototype to play with before
anyone ever starts coding the program in earnest. So, before I
get started, I know what the program is supposed to do.

I have access to the program code - and I have a full programming
environment on my desktop - so I can open the resource file and
get a dump of all the screenshots long before the program is
working well enough to encounter the screens in normal operation.
I use this information to rough-out the context sensitive part of
the online help and as a reference when I outline the book.

Once the coding begins and there are regular builds being made,
I install the program on my computer and play with it. Doing this
lets me approach the program as a brand-new user, which helps me
write from the user's perspective, and gives me a good look at
the user interface long before it's too late to make changes.
(I'll usually give the programmer a bundle of edited screen
shots long before I start writing.)

For most programs, playing with the program is about 85% of
what I need to document it. The other 15% of the information
I get by...

     e-mailing the developer with a list of questions,
     like, "what's the character limit of this field?"

     dropping by the developer's office with a big smile
     on my face and asking, "Hi! Got time to answer a
     question or two? I just can't figure out what this
     button is supposed to be doing."

     giving the developer the first draft of the document
     and asking for technical edits

I'm not really a phone person, so I usually don't call.

Once in a while the developer will come to my office to
answer questions. When that happens, I have a white board
to draw on and toys (tops, puzzles, slinkys, etc.) to
play with so they're comfortable.

All in all, I'd say that I spend less than an hour a week
questioning developers -- and sometimes it's no time at all.

-Sue Gallagher
StarBase Corp, Irvine CA
sgallagher -at- starbasecorp -dot- com