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:Re: Looking for samples From:Ben Kovitz <apteryx -at- CHISP -dot- NET> Date:Sun, 21 Mar 1999 03:49:52 -0700
Sean Olson wrote:
>I have just found this list and really enjoy it, but can anyone tell me if
>the pronunciation for "techwr-l" has been worked out? I found myself
>stumbling mid-sentence as I told my grad advisor about it. Having a name
>would really help.
It's pronounced "techwhirl". Participants are "techwhirlers".
>The main reason for this post, however, is to solicit contributions. I am
>an M.A. candidate at CSU San Bernardino in the department of Composition
>and Rhetoric writing my thesis on Technical Writing and the community of
>technical writers. While I am still in the topic narrowing phase of my
>research, I am generally interested in how standards of good writing are
>developed and the effect of the Internet on that process. Some general
>questions I am attempting to answer include:
>* Is there a community standard for good writing?
Not really, though some people would like there to be "professional
standards" as if tech writing were some sort of profession like accounting.
I see it more as a craft like carpentry, where common sense and a feeling
for the materials matter far more than following published rules and
procedures.
>* How is it defined?
By fawning, uncomprehending mimicry of the ways that standards get set in
professions that have genuine need of published standards.
>* What are the characteristics of good and bad technical writing?
Good technical writing is useful to its audience. Bad ain't.
>* What are the issues of contention?
How many spaces to put after a period.
>* Is there a significant difference between what technical writing manuals
>prescribe as the elements of good writing and those used by the community
>of technical writing practitioners?
>* If so, what are they, and how do you account for the discrepancy?
Depends on who you ask.
>* What affect does the rapid advancement of technology have on any
>disparities between prescription and practice?
A lot of tech writers insist on following rules of usage from speech
communities that don't know from technology. For example, many tech
writers insist on following old "rules" like "'increment' can only be a
noun" even when writing for programmers--a speech community that has
created a different rule, for reasons related to the technology. People
with this attitude are a disgrace to the craft. They are obstacles to
giving people the information they need to do a job, not the deliverers of
this information. They don't *listen*, and listening is the first and
longest task in writing a manual.
>* What is the effect of a virtual community on the development of
>standards.
Who cares? Real tech writers have better things to worry about than
piddly-poo "standards". Real tech writers are trying to figure out what
information people need in order to do a job and how to present it to them
in the most useful form. They're addressing the particulars of that one
audience and that one job--not conforming to some "standard" that abstracts
out all incommensurable differences among audiences and jobs. They learn
and re-apply techniques that can apply to more than one job, but they don't
apply a technique for the sake of saying that they applied a standard
technique.
>I am not necessarily submitting this as a survey, expecting a detailed
>answer to each and everyone of these questions. I am more interested in
>general responses to any of these questions where you might have a
>particular insight or strong feeling. Also, I need to gather writing
>samples. Do you have any masterpieces of good and/or bad writing, not
>necessarily your own, that you can share with me. If you have one of each
>that would really be great.
My book has a number of small examples of good and bad technical writing in
requirements documents for software projects. See links in .sig below. Or
save yourself some money and look at chapter 15 on-line at the Manning web
site. That has a few examples of how to fix certain common mistakes in
technical writing in requirements documents.
I guess I'm in a crusty mood right now, but I hope this helps.
