Summary of Responses

[sheldon kohn <sheldon -dot- kohn -at- MCI -dot- COM>]

Thanks to everyone who responded to my request for input regarding my
problem with the design document. Several people asked me to post a summary
to the list. Per request of some responders, I am not including anyone's
name or contact information in this message.

Summary of My Request for Input

My challenge is to create a "design document" for a new Java product. The
development team is required to prepare and present a "design document," but
the requirements for it are not clear. My request was for input from people
on the list as to how I might best define this document.

Summary of Responses

One idea is to create a graphics-intensive document and to focus on how the
product helps users now and how it is being designed to meet the
organization's needs in the future.

Another suggestion is to follow JoAnn Hackos' framework for managing a
documentation project.

Another correspondent suggested a review of a web site that provides an
overview of documents produced during a software development cycle. This
site is available at the following URL:

www.geocities.com/SiliconValley/Lakes/4970/

This site includes valuable information for anyone who needs to produce
project documents during the software-development cycle. I have used these
documents before in other jobs and have always found them to be reliable and
useful.

Another suggestion is to divide the overall project into primary and
secondary deliverables. The primary deliverable for this project is the
design document, and the users' guide becomes a primary deliverable as the
Design Document takes shape. Work on the Administrator's Guide (set-up and
troubleshooting information) can proceed concurrently with the two primary
deliverables. By ensuring that the users' guide includes examples,
procedures, and task instructions, a separate training guide is probably not
necessary. My schedule should also include some breathing room, or I am
likely to get overwhelmed.

Another suggestion is to begin by producing a design object model, though
this will take a good bit of time with the developers and myself hashing
things out on a white board. The design object model shows the relationships
between the key classes and how these relationships are to be designed and
implemented in the code. This responder found object-oriented analysis and
design to be inherently interesting, and I have to say that I agree.

Another person recommended an approach of mapping requirements from the
requirements document to the corresponding functionality written into the
design document. This allows everyone on the team to see which requirements
are being met as work on the project progresses. There are numerous forms
for such a map: it should be visual, accessible, easy to update and
maintain, and user-friendly.

My Impressions

Thanks to all who responded to my request for input. I have completed my
review of the existing documentation for the project and am now completing
the information plan.

If anyone has other suggestions, please feel free to post them. I do not
have a complete handle on this project yet, and I remain open to and
grateful for suggestions.

Kindest regards,

Sheldon Kohn
Technical Writing Consultant

 From ??? -at- ??? Sun Jan 00 00:00:00 0000=