Re: technical documentation for software

[Dianne Blake <write-it -at- home -dot- com>]

Sandy wrote:

> We're trying to establish what the minimum requirements for documentation
> are:
> *       Service Request (actually the User's document)
> *       Application Requirements
> *       System FlowChart
> *       Data Dictionary: Description of Files and Databases (DBAs are
> actually doing this part)
> *       Technical Information needed for Testing, Installation, Maintenance
> *       Application (Version) Release
> 
> I'd also like some hints for getting this info from developers to tech
> writers, since tech writers are responsible for getting this all down on
> paper.

I can give you a few hints as to what to do, but this will take a lot
longer than 3 weeks and the cooperation of others on the team.

   * Data Dictionary: (hopefully the easiest) If they are using a tool 
     such as Oracle, the software has internal tools to extract the 
     information (which is why the DBAs are doing it)

   * Application Requirements: You should be able to go to marketing
to get
     a start on these. After all they are the ones who (hopefully)
have
     determined what your customers require from the product.

   * System Flowchart: I think the closest you will come to this is
maybe
     a product architecture document. A project or product manager
should
     be able to quickly diagram how the product works on a white
board.
     Based upon this and the product requirements you could at least
piece 
     together the larger picture of the product flow.

   * Technical Info for testing, installation, & maintenance: this is 
     probably three different documents. 

     * See your QA team for test scripts, test plans, or other
information 
       they should already have for testing the product before it is
shipped.

     * Installation: Depending upon the product this might be
something you
       or someone in operations can do on a test system for you. Set
an 
       appointment to do an installation and document the process.
This 
       might be something you would document in a "Quick Start" guide.


     * Maintenance: I'm not sure what you mean here. This is probably
an
       operations manual, that would include such things as how to
start
       up or recover the database. Since I'm not familiar with your
product
       I don't know what needs to be maintained. A good operations
manual
       covers such things as backups, recovery, start-up scripts, etc.

     * Release Document: You really can't write this until code has
been
       frozen, testing is complete (or very near completion) and all
of the
       outstanding issues have been identified. This document includes
a
       run down of new features, known bugs, bug fixes, and any
warnings
       or issues that the end-user needs to know about (including any
       compatibility issues with other service packs for other
products).

     * User Guide: Depending upon the product, this is where you would
work
       with testing, marketing, and developers to determine what the
user
       needs to know to "successfully" use your product. I often find
myself
       in the role of writer/tester. I find that I can best write
about the
       product if I use it. This saves me many interviews and while
using it 
       I can report issues I run into including bugs and usability.

As to your last request for getting information from developers. I
think you will note that in the above descriptions that the
developer's seldom need to be bothered. Developer's are only part of
the team and you need to learn to use all your resources. I find
however that when I do need to extract time from developers (in fact
anyone on the team) that I first do as much fact finding as I can
before going to the person. Then I set an appointment with the person
and never take more than a half-hour of their time. I usually email my
questions to them ahead of time (if I can). Then I use my time wisely
being sure to write down my findings (so I don't have to go back to
them again with the same questions).

As some of the other respondents said, the job of being a technical
writer can be overwhelming, especially given quick out schedules. As a
consultant I often walk into these kinds of situations. Before you
start, sit down with someone to determine your priorities. Determine
what documents are needed by when. Explain what it is you need to do
(that will often get them thinking in more realistic terms). Then get
to work and use all your resources.

Good luck to you.

-Dianne Blake
Consultant, Writer and Trainer
write-it -at- home -dot- com

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Develop HTML-based Help with Macromedia Dreamweaver! (STC Discount.)
**NEW DATE/LOCATION!** January 16-17, 2001, New York, NY.
http://www.weisner.com/training/dreamweaver_help.htm or 800-646-9989.

          Sponsored by an
 anonymous satisfied subscriber since 1994.

---
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.