TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Request for Input From:sheldon kohn <sheldon -dot- kohn -at- MCI -dot- COM> Date:Wed, 9 Dec 1998 08:03:09 -0500
Hello Fellow Tech-Whirlers,
I have been hired as a consultant to develop a "Design Document" for a new
Java-based application for a telecommunications company. Two factors make
the situation interesting. First, I am a trailblazer. The company has hired
me to "show what a technical writer can do." If I impress management, it
will open up some nice opportunities both for me and for other technical
writers. Second, there really are no specific guidelines for what is to be
included in the "Design Document." It is intended for developers and system
administrators. There are a lot of existing "Design Documents" for other
projects. They are more-or-less functional specifications and not very
interesting.
Existing documents for my project include a somewhat accurate requirements
document and a disorganized detailed design document. The other team members
are glad to have me and are quite supportive. They all want this project to
succeed, and they all want a technical writer to be heavily involved with
the team, though they are not sure exactly what I can contribute. They do
know that I can help them look good to management, which may result in
additional projects.
I am three weeks into the assignment. To this point, I have been working on
an information plan and extracting relevant information from the existing
documents.
Although I have some ideas of the structure and contents of the
deliverables, I would like to know what people on the list think is
appropriate in this situation. Although no one has said so explicitly, I
have the impression that there should be three deliverables: a design
document, a production support manual focused on troubleshooting, and a
combination user guide and training manual. There is little interest in
providing the users with on-line help or in using FrameMaker to create PDF
files. I have been instructed to create Word documents that end-users can
download and print if they wish.
Please feel free to send me comments and suggestions directly. If there is
interest, I will summarize for the list.
