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:FW: Source: Computer Software Design Document Description/Samples Needed From:"Margaret L. FalerSweany" <mfsweany -at- MTU -dot- EDU> Date:Wed, 6 Nov 1996 10:48:27 -0500
Note: If you wish to reply privately to this at mfsweany -at- mtu -dot- edu, I will summarize your advice to the list--should there be interest by others.
My husband teaches a 300-level software development methods course where he's supposed to help students to learn how a piece of software is created from the first idea. One of the mysterious steps is the "Design Document" that should layout the scope of the project in some way. He has asked me for sources that describe what should be in a design document and how one might put them together? Where could he get useful, functional samples to show his CS majors? Who should be on the design team, how do sections get developed/assigned, etc. What connections there should be between the design document and the documentation that would accompany the final product--(I keep encouraging him to talk with his CS majors about getting tech communications people into projects early and how to play nicely together ;) )
I work on scientific writing of a different nature and can't help him, but I know a lot of you work in this area and might have some ideas of where he can get some help. Also, do you get involved in such documents as tech communicators?
Caveat: Phil is resistant to the idea of a design document because of two experiences he had. 1) In industry position he was asked to prepare such documents at the beginning of a compiler production project. But, he says that no one seemed to know what should be in such documents, what level of detail was necessary, or what connections there should be between the design document and the documentation that would accompany the final product--if any. He was just told to write it and when the document was done, he was told it wasn't what was needed and to redo it, but no one seemed to know what they wanted. 2) He's working with an EE engineer who has 20+ years of industry experience and insists on a design document that includes actual code that will be implemented. This seems to be overkill.
Industrialism will not be undermined
by the barbarians at the gate, but by
the awakened within.
Roy Morrison _Ecological Democracy_
Rhetoric & Technical Communication
Michigan Technological University
Houghton, MI 49931
mfsweany -at- mtu -dot- edu