From: horen@netcom.com (Jonathan B. Horen -- [408] 736-3923)
Subject: Re: So much CS, so little time [LONG]
Organization: NetCom -- OnLine Communication Services
Date: Sat, 12 Dec 1992 23:44:20 GMT

In article <11DEC199215300110@csa3.lbl.gov> jtchew@csa3.lbl.gov (Ad absurdum per aspera) writes:
>A few newsreader timeout periods ago, someone (our moderator, as I 
>recall) spoke of putting technical writing students through what
>was essentially computer-science coursework in the design of word
>processors, getting their feet wet in data structures and so forth.
>
[grammar-checker example deleted for brevity's sake]
>
>As is usually the case when bad things happen with good software,
>that may be an oversimplification, but there are a lot of ways in
>which the grammar checker (and some large though finite number of
>other features) might have benefitted from design-stage input by 
>an actual writer.  This input, of course, would be better directed
>if the writer understood something about the innards of software 
>(if only to know when something really was unfeasible and when the 
>programmers were just copping an alibi :) in addition to grammar.
>
[more stuff deleted]
>
>I don't suggest that a minor in CS be a requirement for tech-writing
>majors, but some of them certainly take that path.  Now:  how to
>get them to infiltrate software companies and subvert the programmer-
>dominated culture with the requirements of demanding, expert users?  :)

As I see it, there are really two issues here:

   1.	Technical writers need formalized (read: classroom) training
	in Computer Science; and

   2.	Computer-savvy technical writers need to be integrated into
	the software-design process.

Both issues are timely and relevant, and neither one is something
"new under the sun". As a professional technical writer with some
17 years writing experience (although only the last ten in the area
of computers and computer software), and as a professional Sun
systems administrator, I would like to add my $0.02 

It is only within the last decade (please correct -- *not* flame --
me if I err) that Technical Writing has been a "major" at colleges
and universities; some even have Masters-degree programs in this
discipline. As such, it seems to me that there needs to be greater
communication between industry and academia about the requirements
(present and perceived future) for a technical writer.

But I have yet to meet a technical writer with a BA/BS in Technical
Writing. I have met technical writers who:

   o	were English/Journalism majors, who found their way into "industry"

   o	were CS/EE majors, who had on occasion been tasked with documenting,
	and found that they liked it more than coding

   o	(like myself) were not college graduates at all, who entered the
	field in the military, or from other backgrounds

With regard to the second group, the first issue is a non-issue. However,
it is with regard to the first and third groups that the "real" issue
exists -- that is, who is responsible for `teaching old dogs new tricks'?

Because the `new tricks' about which we are concerned are in the category
of "requirements" (read: prerequisites), it is clear to me that it is
up to the technical writer to educate himself -- he must become an
"auto-didact". This is not such a `chidush' -- it is what all of us do,
anyway, and regardless of whether we are technical writers, or not.

The second issue -- integrating computer-savvy technical writers into
the software-design process -- is of much greater importance, both to
the technical writer, as well as to his employer. Doing so, however,
has proved to be (virtually) impossible. Here are some reasons:

   o	Most software is "built", rather than "designed"

   o	When software *is* "designed", few companies adhere to the
	highly-structured development practices of Mil-Std 2167/2167A

   o	Even when software is designed IAW Mil-Std 2167/2167A,
	over-committment of project staff and/or inter/intra-
	departmental politics prevent the exchange of information

Modern computer folklore is replete with examples of the first and
second groups -- examples of both corporate failure *and* corporate
success. In the majority of cases, the failures never had a chance
to learn from their mistakes, while the successes rarely (if ever)
feel that there is any lesson to learn...

As for the third reason, it is only large corporations which can
(or better, "which have") create separate R&D and Software Engineering
departments.

Note:	I differentiate between R&D and Software Engineering on the
	basis that R&D would be performing the initial and detailed
	design phases of a project (during which time the techical
	writers would be integrated and already writing), while the
	Software Engineering group would be creating the code based
	on R&D's detailed design *and on the already-written
	documentation*.

I have worked at small- (50 employee) and medium- (150 employee)
sized companies, both here and abroad, and every attempt to manage
a software project to its successful completion has failed (and I
lump "mediocre" together with outright failure). This is regardless
of whether computer-savvy technical writers were integrated, or not.
Invariably, the reason for project failure was that either project
members from software development were over-committed to other
projects, or that politics within the software-development department
(or between it and other departments) prevented the project team
from cooperating.

You cannot build a brick wall without the proper foundation and,
even with the proper foundation, if the rest of the wall is built
haphazardly the wall will not last.

So, too, with computer software.

Personally, I think that it has everything to do with the last
decade's preoccupation on the part of corporate America with short-
term profits, and an inversely-proportional regard for the long-/
medium-term benefits of research and development.


Jonathan B. Horen
Sun System Administrator/Sr. Technical Writer
tel: (408) 736-3923 | email: horen@netcom.com
Newsgroups: comp.edu.composition