RE: spec / product / interview?

["Susan W. Gallagher" <SGallagher -at- akonix -dot- com>]

> -----Original Message-----
> From: Jane Carnall [mailto:jane -dot- carnall -at- digitalbridges -dot- com]
> 
> I've noticed that often technical writing job adverts (or the 
> job specs, or ... interviewers) ask that the technical writer 
> ...provide a user guide with the product and the spec (or 
> sometimes just with the spec).

It depends on the level of detail of the spec, of course, but
*in general* the spec is a document with inward focus and user
guides must have outward focus. By that I mean that the spec
details *what* the product does; it does not necessarily touch
on *how* someone would use the product. The developers suffer
from the same curse; they're concerned with making the product
work and often cannot step back to see the how of things.

So, yes, in general, I agree that the spec cannot fulfill 100%
of our needs. But often, neither can the developers!  ;-)

> While it's true that with a working copy of the product, and a good
detailed
> specification document, it would be possible to put some kind of user
guide
> together, my feeling is that for the best possible output, the technical
> writer needs access to the developers (and the testers, and marketing or
> whoever can tell you just what the users are likely to want to do with
this
> product). 

I frequently pester all of those people to gain an understanding of 
the product and the audience. However, sometimes it takes research
into the subject matter and it becomes necessary for us to become
quasi-SMEs before we can create an effective user guide.


> Sometimes the product isn't working yet and the spec isn't ...
> detailed ... and the *only* way to put a user guide together is
> to talk to the developers and get the information that's in their heads or
> in their unofficial working notes.

Yes. Although there are ways to get around even that. I've been caught with
my fingers in the resource file often enough -- printing out half-assembled
screens and deducing the functionality. Often it's enough to spark a decent
technical review, where you can really get information.

I've even documented conversations in the hallway!
Dev: We're going to make the product prompt to save when you exit
Sue: okay! <write, write, write>
Dev: <read> That's not what it does!
Sue: But you said "prompt". *That's* what "prompt" looks like. What
     did you *really* make it do??? 

(that's the science fiction part!)  ;-)

> Yet I get the feeling sometimes that management feel you *ought* to be
able
> to do it without (ahem) "wasting the developers time asking them
questions"
> (sometimes you feel the developers feel this too, but there are techniques
> to get round awkward uncooperative developers, particularly when you know
> you have managerial support). So: how to get managerial support for
> something that they think you don't or shouldn't need?

I often think we become too reliant on the interview process to gather 
information and that we should perform our own research and reach our
own conclusions before we approach development -- that we need to become
more self sufficient. And I think that if we demonstrate our willingness
and ability to be self sufficient and only contact "the devs" when we 
really neeed them, we'll have a much easier time enlisting management
support.

(That said, much of what I've said is dependent on the application we're 
documenting. It's certainly easier to research and answer our own questions
when we're documenting an end-user app as opposed to an API.)

Another thought is that we often fail to fully integrate ourselves into
the development team, so when we need to have questions answered, we find
ourselves being formal about requesting interview time with the devs. Our
managers view this as an imposition on dev time, and they're often right.
These formal interview sessions eat up bug-fixing time, so management has
a right to show concern.

When we become a part of the social interaction of the development team,
we often stumble upon the kind of information we need informally -- during
conversations at lunch or just from catching an off-hand remark. So we
gather the information we need informally and without eating up development
time.

And I've been rambling, so let me sum up. It isn't that we don't need to
interface with the devs -- we certainly do. But we can do so less frequently
and less formally to mitigate our impact on the dev's schedule. Because it
isn't that management doesn't want us to get info from the devs, it's just
that they don't want us to impact the schedule.

And reviewing this message sparked another thought, and that is that we need
to make sure our goals are in line with management's and development's goals
for the product. You said:

> ...it would be possible to put some kind of user guide
> together, my feeling is that for the best possible output,...

Sad to say, management doesn't always want "the best possible output" -- we,
OTOH, almost always do. So we need to make sure that we're not chasing
rainbows
and bogging the rest of the team down in mud.

Enough with these thought-provoking questions, Jane! ;-)

-Sue Gallagher
sgallagher -at- akonix -dot- com




^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Collect Royalties, Not Rejection Letters! Tell us your rejection story when you 
submit your manuscript to iUniverse Nov. 6 -Dec. 15 and get five free copies of 
your book. What are you waiting for? http://www.iuniverse.com/media/techwr

  Your monthly sponsorship message here reaches more than
  5000 technical writers, providing 2,500,000+ monthly impressions.
  Contact Eric (ejray -at- raycomm -dot- com) for details and availability.

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.