Re: Software documentatio

Subject: Re: Software documentatio
From: Brian Bennett <bb18+ -at- ANDREW -dot- CMU -dot- EDU>
Date: Mon, 8 Aug 1994 11:25:34 -0400

Sorry if I might be jumping into the middle of a discussion, but this is a
subject about which I feel very strongly. Of course writer's should be
involved in the initial stages of product design. The fact is, however,
that most writers don't really have a grasp on how they can be of help at
that stage. Sure, if you're involved in early design your job of
documenting will be made a great deal easer (and arguably, this has benefits
to the organization as a whole) but if the writer doesn't show how he/she
can produce quantifiable benefits, he/she has no right to expect to be involved.

I would suggest starting out by offering to help with specification
documents. Of course, this requires some investment of your time, but if
you can present your involvement as a great help to the organization by
saving others' time (through actually taking on some of the workload and
also by making the specs more clear for those who need to use them) you will
be taking the first step to becoming an integral part of the design team.
This also gives you a built-in path to expressing your opinions and
challenges to the design.

As you learn more about the purpose, structure, and content of specs (and
you will need to learn if you haven't done it before) you can begin offer to
take on some of the actual design work. If this is not your goal, then you
may stop at being involved with the spec writing.

At the company where I used to work (one of the top ten independent software
vendors) the documentation manager made a great deal of noise to get
documentation involved in the early design of the software. However, once
the writers were involved, they showed, more often than not, that they had
absolutely nothing to offer the team. This produced, as far as I'm
concerned, more negative results than positive.

When I arrived at the company for which I now work, I was the first
"official" technical writer the company had had in ten years. I immediately
set out to show the development team what I could offer them (I had
accumulated a great deal of interface design experience at my previous job)
and quickly, and quite easily, became a part of the design team. In fact,
documentation is now responsible not only for the design documents, but for
the external design of the software in general.

This is the procedure:

1. Determine the needs of the design team (not your needs;
nobody cares about those but you) that you
are willing and able to fill (make sure the design
team also sees them as needs).

2. Show the design team how you can produce QUANTIFIABLE
results (saving writing/production time with the specs,
making them clearer, etc.).

3. Make sure you follow through on your promises. If you
are a manager, make sure you don't get your writers into
situations that they are not prepared to handle. You may
have to invest in training/education for you and/or your
writers to make sure they will produce results.

In short, no amount of screaming, foot-stomping, and flailing of the arms
will get you the right to a seat on the design team. I believe that writers
can be very valuable to the design team in the form of user advocates. But
if you view your involvement as a benefit only to you (i.e. "It makes my job
a lot easier if I'm involved early on.") then you're not going to get
anywhere. If management's argument is "what could a bunch of writers know
about software architecture," don't try to argue. Attack from a different
perspective and SHOW them what you know.


>Date: Sun, 7 Aug 1994 08:20:51 EDT
>Reply-To: MollyDee <MollyDee -at- AOL -dot- COM>
>Sender: "Technical Writers List; for all Technical Communication issues"
<TECHWR-L -at- VM1 -dot- ucc -dot- okstate -dot- edu>
>From: Debbie Molinaro <MollyDee -at- AOL -dot- COM>
>Subject: Re: Software documentatio
>Comments: To: techwr-l -at- vm1 -dot- ucc -dot- okstate -dot- edu
>To: Multiple recipients of list TECHWR-L <TECHWR-L -at- vm1 -dot- ucc -dot- okstate -dot- edu>

>A>> At what point in the fabled software lifecycle do most of you
>A>> beginning creating documentation?

>A>All of us who have been there (and we are legion) empathize
>A>with your situation. However, I believe it is absolutely
>A>vital that pubs folk be part of the initial design team,
>A>and have their hands on the product from the word go.

>I agree whole heartedly...
>What's a writer to do when the software organization is very secretive (and
>adamantly so) until well after initial design? I have such a situation. By
>the time any "outsiders" were brought into the loop, many features and
>characteristics were already written in stone.
>When we tried to challenge this, the impression was that we were just
>responsible for documentation and not design... after all, what could a bunch
>of writers know about software architecture.

>It's too late for this product, but some advice would be appreciated for the
>next product.

>= = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
>Debbie Molinaro
>MollyDee -at- aol -dot- com
>molinaro_debbie -at- ny -dot- mrc -dot- sony -dot- com

>"I personally think we developed language because of our
>deep inner need to complain." -- Jane Wagner/Lily Tomlin
>= = = = = = = = = = = = = = = = = = = = = = = = = = = = = =

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

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


Previous by Author: Bad resumes
Next by Author: Re: Software documentatio
Previous by Thread: Re: Software documentatio
Next by Thread: Re: Software documentatio


What this post helpful? Share it with friends and colleagues:


Sponsored Ads