Re: Software documentatio

[Elna -dot- Tymes -at- SYNTEX -dot- COM]

In article <199408081941 -dot- PAA16613 -at- andrew -dot- cmu -dot- edu>, <bb18+ -at- andrew -dot- cmu -dot- edu>
writes:

> The instances in which the writers became actively involved in the design
> were always positive (I'd like to think that mine was such a case).
<<snip>>
> If you're going to lobby for a role on the design team, make sure you can
> actually contribute to the team.  In an individual case (in which one or two
> writers are dealing with a specific development team) this probably wouldn't
> be a problem.  But when a manager makes demands that a number of writers be
> involved with a number of development teams across-the-board, he/she must
> make sure that the individual writers will be able to perform adequately in
> the role.  If not, some amount of resentment can build between development
> and documentation if development sees no tangible benefits to involving
> documentation in design.

<<snip>>

> Another perceived cost may be that they see the writers as not having the
> technical knowledge to keep up with the group, and therefore might slow down
> the process.

Granted it is difficult to get engineers and programmers to recognize that
writers sometimes do, indeed, understand the technology.  What is often more
difficult is getting them to understand that the writer is basically a "user
advocate," and that what this person brings to the design part of the effort
is a perspective many techies not only don't understand, but sometimes don't
even acknowledge.

I have a private campaign going against character-based interfaces.  I find
them difficult to use, difficult to explain, difficult to teach effectively.
It was with privately smug satisfaction that I heard of a development project
locally that was resoundingly rejected by the internal users, because it was
character based and difficult to use. So the development team, suitably
chastised, went back to the conference table and THIS time they involved a
writer in the planning.  It became clear that the users didn't need to know
the technology behind it all, but the writer knew enough to understand why
some suggestions would work and others wouldn't.  It also became clear to
the developers that if the writer thought the interface was difficult to use,
the users would also find it difficult.  The writer, of course, had to deal
with the entire team "forgetting" what it meant to freeze the screens at a
particular date.  Nonetheless, the product relaunch was very successful, with
the product/documentation/training/Help systems getting rave reviews.

The point of this is that the development team learned WHY it is important
to involve a writer - that the writer provides a much-needed user perspective
in the design phase, one which techies tend to forget while in the midst of
inventing new ways of doing things.

Elna Tymes
Los Trancos Systems