Re: Software documentatio

[Brian Bennett <bb18+ -at- ANDREW -dot- CMU -dot- EDU>]

At 12:46 PM 8/8/94 -0400, Laurie D Mann wrote:
>I used to work for a computer company, and we also pushed for years to
>get writers involved earlier.  Sometimes it worked well, and sometimes
>the writers didn't do the leg-work and didn't get involved adequately.
>But I'd say it was more positive than negative.  It took more work ont
>he writer's part earlier on, but the final product tended to be better.


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).
However, I believe the overall effect of lobbying for a position on the team
them doing next to nothing with it (which was the case most of the time) was
negative because of the way the involvement was sold to development.  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.


>You're generally correct about "showing them what you know," but it can
>take a few months to a year depending on what the product is.  Better to
>get in early and try to soak up some of the material rather than give up
>without even trying.


If you can get development to involve you without expecting immediate
benefits, there's no problem with that.  In such a case, the development
organization is probably mature enough to realize that involving
documentation in design will have overall benefits for the product (i.e.
more timely documentation, better quality documentation) even though the
development organization does not benefit directly.

However, development will most likely see a "cost" to involving
documentation in design.  If there is already more than one group involved
(development, marketing, technical support, QA), they may feel that another
group will make it less likely that the group can function efficiently.
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.

My point is that simply pleading to be involved most likely will not get you
anywhere and, in fact, may damage relationships.  You're right; it may take
months or even years to show development what you can do for them in "the
big picture."  But taking on some tasks that will have tangible, short-term
benefits to development will help you to get your foot in the door.  If
you're in an organization where you are accepted readily without having to
go through the pains of proving yourself to be a valuable part of the team,
then it's probably a fairly mature organization.  I don't think most people
are that fortunate.

Brian

  ___________________________________________________________
  ___________________________________________________________
  Brian S. R. Bennett
  Senior Information Developer
  H. B. Maynard and Company
  Eight Parkway Center
  Pittsburgh, PA 15220

  Phone: 412/921-2400 ext. 123
    FAX: 412/921-4575
  ___________________________________________________________