Re: TECH. WRITING SURVEY - OPINIONS REQUESTED

[Jim Purcell <jimpur -at- MICROSOFT -dot- COM>]

Jack W. Bonney wrote:

> ----------
> Subject:      TECH. WRITING SURVEY - OPINIONS REQUESTED
>
I'm beginning to think that on this list, "survey" is a synonym for
"trawling for flames."

> we are conducting research into the work undertaken by "technical
> writers", either as employees or under "freelance contractors".
>
The word that belongs in quotes here is "research."

> if you are involved in any way with documentation and manuals, both on
> paper or electronic, and as managers or readers as well  --  then we
> would
> appreciate receiving your knowledgeable comments and opinions on any
> or
> all of the following observations:
>
Nevertheless, a serious attack requires a serious response, so I will
try.

> 1.  a study by xerox reported in 1986 that more than 80% of all
> manuals
> produced by the fortune 1000 companies were seldom opened more than
> twice;
> this represented an estimated 3 trillion pages costing $75 Billion.
>
While this is an interesting statistic, I'm not sure what it has to do
with technical writers. The Fortune 1000 includes a lot of companies
that generate a lot of paper, not all of it (maybe not even most of it)
technical in nature. Three trillion is a lot of pages, which I imagine
includes a lot of policy and procedure manuals whose contents are
normally communicated to the masses orally or in summary. Another large
component is probably CYA-type documentation for legal purposes. Without
a breakdown of this number, we can't know what all these pages consist
of, and so we can't conclude anything useful or interesting.

> 2.  an analysis of more than 40 textbooks on how to prepare "manuals"
> shows that the fundamental process remains unchanged since before
> world
> war II; replacing a typewriter with a computer has done little to
> reduce
> the time and costs involved nor to improve the quality of the results.
>
The first part of this statement should come as no surprise to anybody.
The way books get researched and written hasn't changed much either. We
may do some of our research on the Web or through Lexis/Nexis or
whatever, but the research phase is what it always was. We still write,
get reviewed and edited, rewrite, and so on. Why would computers change
that?

The second part is really not a big surprise, either. Writing is not
typing. While there are some incremental gains in productivity from
computers, particularly in making revisions and corrections, by
themselves they would not justify the expense of all those computers and
all that software. Where computers pay their way is in document
production, not in the writing itself. If writers still used
typewriters, the production staff would have to manually reproduce all
those words, at great expense.

I do take issue with the subliminal message at the end of this
statement: "replacing a typewriter with a computer has done little ...
to improve the quality of the results." This statement is true as far as
it goes, but the implication here is that documentation is just as bad
as it ever was. Documentation is getting better every day, not because
we use word processors but because we as a profession have better
training, more experience and research about audience and task analysis,
and more writers and editors who have both technical and writing skills.


> 3.  the wrong people are using the wrong tools in the wrong way to do
> this
> work; the vast majority of "technical writers" (including in-house
> employees who "did" the policy manual) were never trained nor hired
> for
> the work, and personally don't like doing it.
>
Nobody should accept a sweeping generalization like this without
supporting research. In any case, this statement lumps things together
that have no relation to one another. Many technical writers do not have
formal training in the field, were not originally hired to be tech
writers, and yet love their jobs. TC as a profession is still in its
infancy, so of course there are a lot of us who were not originally
"trained [or] hired for the work." But already there are degree
programs, professional societies, and journals theoretical and
practical. Are there technical writers who don't like what they're
doing? Of course there are, just as in all professions. Are they "the
vast majority"? That would be news. Show me numbers.

And who are these wrong people? What are these wrong tools? What is this
wrong way? And who says so?

> 4.  most technical communications groups appear to be network forums
> for
> find project-related jobs or for "ad hoc" frequently asked questions
> about
>  how to do the work  --  very little is done about research into the
> work
> and the disciplines and techniques that are involved.
>
This is probably as it should be. A lot of TC work is short-term
freelancing. Job hunters must look where the potential employers are,
and employee seekers must look where the potential employees are. This
activity does not trivialize lists like this one.

As to the second part of this statement, I find that participants in
this list (for example) are pretty well-informed about theory and will
often use research to make a practical point. That they are not
primarily interested in theory for its own sake should not be
surprising. Working technical writers are practitioners, not
theoreticians.

> 5.  most developers of engineered systems and products do not know how
> to
> interface with those who must prepare the documentation needed to
> support
> their work  --  because of this, the real losers are those who must
> rely
> on the documentation.
>
I have never known this to be a problem at any point in my career. In
many cases, developers do not have time to work with tech writers
because such time is not budgeted into their projects and their managers
view time taken from product development as time wasted. This is a real
problem, and indeed the real losers are those who must rely on the
documentation. It isn't a problem of inadequate knowledge, though; it's
a management problem, pure and simple.

> 6.  the key priority of using documentation has little to do with how
> "pretty" the manuals are; readers want 3 key features:
>
>      a.  functional organization,
>      b.  consistent presentation,
>      c.  accurate and complete content.
>
Who can argue with this? Document design should make documents easy to
use, not merely attractive. If the point here is that you don't need
book designers or production people, I have to disagree. A bad document
design can hinder usability just as surely as can poor organization.

> 7.  wordprocessing and page composition packages are not "systems"
> i.e.
> they do not process data independently nor add value to it  --  as
> singular work tools, they are extremely labour intensive and clumsy
> for
> the task.
>
I think Jack is confusing data with information here. If writing could
be done by machines, you wouldn't need writers. So far, we don't even
have machines that can read natural languages, much less "process
[natural-language] data independently [or] add value to it." Tools are
always evolving, and people are always complaining about their tools,
but I'd be interested to know what Jack is looking for here.

> 8.  documentation and manuals are an expense -- in most cases, they do
> not
> generate revenue for the developer  --
>
It would be more correct to say that most companies' business models do
not account for the value that documentation adds to their products.

>  most technical writers have no
> expertise in costing and budgeting for this work, address only part of
> the
> entire process, and fail to report the total costs to management  --
>
As opposed to, say, product development teams?

> management has no understanding of the true costs involved and fail to
> appreciate the value and importance of the results.
>
Which is precisely why documentation groups suffer disproportionately
heavy casualties during hard times. It doesn't matter that the "true
cost" of documentation is a microscopic part of the typical product
budget. If the "value and importance of the results" are not recognized,
the documentation is viewed as an expense, however small, to be got rid
of at the first downturn in revenues.

> we will appreciate your contributions and comments; copies of our
> findings
> will be sent to all participants who request.
>
I see from subsequent postings that Jack professes surprise at the
hostile response this post has received. I have to believe he's being
disingenuous. Like the recent c***********n flap, this post seems
designed to generate more heat than light.

Jim Purcell
jimpur -at- microsoft -dot- com
My opinions, not Microsoft's

 TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send commands
   to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
  Search the archives at http://www.documentation.com/  or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html