System Documentation Book: Would YOU Buy It? [Long]

Subject: System Documentation Book: Would YOU Buy It? [Long]
From: "Kendall V. Scott" <SoftDocWiz -at- AOL -dot- COM>
Date: Mon, 4 Dec 1995 20:03:39 -0500

A while ago, Phil Teich posted a query about system documentation materials
that he could study to get a better feel for the nature of the work that's
involved. The list he ended up with was pretty threadbare. I've been mulling
that over, and I've decided to ask all of you for advice with regard to the
potential audience for such a book, given authorship by someone with
particular expertise in the subject (that would be me).

I have a copy of a proposal I sent to a major publisher about a year ago;
they told me that the market would be just too narrow for them to consider
it. However, I am interested in pursuing alternatives, including electronic
distribution (albeit of a version with fewer graphics than I would include in
a full-blown published version).

What follows is a (necessarily) sketchy proposed ToC....

Part I: Introduction
1. Introduction will address various systems development
without assuming any particular one; majority of
book will
be organized around traditional lifecycle, with
extended example
text that tracks progress of brand new system
audience....mainly tech writers who want to get into "sys doc,"

Part II: Getting Started
2. Initial Investigation Reports / Preliminary Business Requirements
documents associated with efforts to reach better mutual
between business unit(s), developers of requested project
3. Project Proposals / Feasibility Study Reports
more detailed kinds of documentation resulting from determination
project appears viable

Part III: Analysis
4. Requirements Analysis
gathering/analyzing/documenting requirements, including discussion
of JAD
5. Data/Process/Interaction Modeling
entity-relationship modeling, class hierarchies, functional
6. Current Systems Analysis
to identify supported processes and data, assess existing
system/doc quality

Part IV: Design
7. High-Level Design
logical databases, system/subsystem diagrams, alternate design
8. Low-Level Design
physical databases, network layouts, screen/report prototypes, func

Part V: Testing
9. Unit and Integration Testing
how to generate test cases, write plans & procedures
10. System and User Acceptance Testing
putting smaller test suites together into full-blown test packages

Part VI: Implementation
11. Conversion
data purification, cutover/turnover procedures, special programs
12. Operator Documentation
job scheduling, error handling, backup/retention/recovery,
including text
about how to analyze JCL/Unix shell scripts

Part VII: Maintenance
13. Maintenance Documentation
program description/maintenance manuals, technical references,
techniqes for analyzing code and translating it into

[Author's note: This chapter is the one nearest and dearest to my heart.
Perhaps a miniature book about this would suffice to start, eh? It's a

Part VIII: Nontraditional Development Approaches
14. Rapid Application Development (RAD)
how to produce specs that will help lead efforts to develop
sample data
15. Reengineering
expansion of "Current Systems Analysis," "Maintenance" to show
how to generate combined design/maintenance documents
16. Software Reuse
how to juggle different kinds of materials (e.g., data modeling
function library maintenance text) when reuse is stated objective

Part IX: Conclusion
17. Conclusion
politics: how the TW can use increasing levels of knowledge as
to increase effectiveness, efficiency as member of development

[One of the technical reviewers of the proposal suggested that this alone
would make for an attractive, if small, book. Yes?]

....and the requisite bibilography and index, of course.

Well, I hope I haven't lost TOO many of you. As you can probably see, I've
been thinking about this book for a very long time, and therefore, comments
of any kind would be most welcome. TIA, BYOB, TGIF, MFSB, ISISAISTHWI.
(You'll have to ask about that last one, I imagine, but anyone who guesses it
gets a free copy of the book! Tee hee....)

Kendall Scott, E.E.S.
(Edification and Enlightenment Specialist)
E-mail: softdocwiz -at- aol -dot- com

Previous by Author: [no subject]
Next by Author: Gender Bias In Re Apostrophes Within Pronouns
Previous by Thread: Fig./Figs. [wide-ranging summary/long]
Next by Thread: Teaching/Learning Writing/Grammar

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

Sponsored Ads