Re: At what point do you include the Information Plan?

Subject: Re: At what point do you include the Information Plan?
From: "R A Downey" <rdowney -at- Matrox -dot- COM>
To: "Cathy De Rubeis" <de_rubeis -at- hotmail -dot- com>, "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 12 Sep 2000 12:27:22 -0400

Hi Cathy.

>Do you think the Information plan should be part of a "frozen" Product
>Requirements document?
In an ideal and perfect world - yes. But realistically you should expect to
write the information plan from a changing Product Requirements
documentation. Make sure that you know who is in charge of the Product
Requirements Document and when that person updates his document - he (or
she) should inform you so you can gage the changes impact on your
Information plan. This is - if anything, a perfect excuse for attending
managerial/engineering meetings.

>Is there enough information in a Product Requirements document to develop
an
>Information Plan?
Again, ideally yes - but probably not. Use whatever it has, but expect to
have to go and talk to the planners/designers/writers of the Product
Requirements document to fill in the information it may lack. Depending on
how detailed your Product Requirements document is will determine if you
have enough information. Making your needs known to the writer may even
convince him to add information.

>Is it the norm for Design documents to be so extensive in documenting how a
>procedure works?
In my company - no, it's not. I've only just begun presenting design
documentation on the future documentation, and as such at times I find
myself buried under an avalanche of information and at others there is no
answers to my questions. The goal, at least as far as I can tell, is to
achieve a balance between getting all the information you will need to
document the procedure/product, and not leaving something out. I have found,
however, having a meeting with those involved has added to the questions the
documentation should answer and straightened out my assumptions.

Relying solely on design documentation is suppose to be possible, but I've
found this isn't a perfect world. I have regularly needed to talk to the
designers to be rid of the confusion their documentation can cause. Software
and hardware engineers are bright people, and I work with a few that are eve
n good teachers - but that doesn't mean they can write clearly.

>Where does the work of the developer end and the job of the technical
writer
>begin?
Ideally they should mesh. At times you may have to work with the developer
to understand concepts, and at other times he (or she) may have to work with
you to bring clarity to their documents. You should not have to design
anything other than the documentation (this includes manuals, online help,
etc). I like to have a say in the Graphical User Interface (GUI), but it's
not mandatory; and I don't actually design it - I'm just one of the folks
who gets to comment on its ease-of-use and appearance.

I also like to be in the developer meetings whenever possible. I do not
attend code reviews, as I'm not a software engineer or a programmer I cannot
add to those meetings. But I do attend "concept" meetings (where ideas and
theories are discussed). I also try to talk to the senior engineers about
once a week to find out what's new and how it's going. I tell them early in
the design process about my needs and remind them from time to time in
review meetings (where everyone in a project gets around a table and details
what they've done for the last week).

>Do you think introducing an Information Plan after the Design documents are
>completed is too late in the process?
The information plan, if presented after the design documents is still
valid, but it may cause more of a headache - especially if the design
documents still don't provide you the information you need. If anything the
Information plan and all following documents need to be occasionally
reviewed to assure you've not missed anything in revisions of the design,
architectural and product requirements documentation.

Personally I try to think of the information plan, and all documents that
follow it - as living documents that will grow and change with time. I list
mark all updates and revisions in the documents so that, when it comes time
to review my plan of attack on the project - I can see what changed and how
well (or how poorly) it was handled.

I do not like writing much beyond the information plan if there is no
prototype of a GUI from which I can work - but I have done it. I've even
written documents on projects that do not yet exist. My information has come
totally from the designers and their documents as well as interviews. In
cases where the GUI is 90% of the product (i.e. it's a software product that
actually has a GUI) - trying to write without even a prototype (not all the
buttons or functions may be defined in a prototype, but at least you know
the general hierarchy and parts) is a waste of time as most all of it will
have to be rewritten. There are exceptions (especially when dealing with
hardware installation and theory - as there's only so many ways to connect
things and the theories on which the product is based should be defined
early on.)

I hope this helps.
Please tell the list what you intend to do, once you decide.
Thanks
---
R. Downey
Matrox Networks
Technical Writer
e-mail: rdowney -at- matrox -dot- com
web: http://www.matrox.com/networks





Previous by Author: RE: Humor in technical writing
Next by Author: Re: Copyright: another resource
Previous by Thread: RE: At what point do you include the Information Plan?
Next by Thread: Word Help: SOLVED


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

Sponsored Ads


Sponsored Ads