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:Inventing definitions (Was: What is a document?) From:Ben Kovitz <apteryx -at- CHISP -dot- NET> Date:Wed, 10 Mar 1999 13:54:25 -0700
Jeroen Hendrix wrote:
>I know some of you won't find this an important or even interesting issue,
>but it exists here at my place. In our Q&A program, the process of
>documentation is described as well. Part of the Q&A exercises is to define
>corporate terms. In the terms and definition list, the following definition
>of the term *document* came up:
>
> Document: A medium and the data recorded on it for human use. By
>extension, any record that has permanence and can be read by man or
>machine.
>
>To me, this definition is unworkable. It is vague, everything can be
>interpreted as a document by this definition, even a file, a video cassette
>or credit card. Now the trouble is to come up with something better. To me
>a document is an information carrier, with contents that can be read and
>interpreted by humans. Machines don't read documents, but data. Can
>anyone out there think of a better definition? Or tell me what you use in
>your workplace?
There is a great danger here of confusing a semantic question with a
substantive one: asking which of a set of different concepts is true (a
category error) instead of asking something about a certain part of the
world or asking what are the uses of certain, distinct ways of
distinguishing a part of the world (those would be sensible, substantive
questions). Happily, it hasn't happened here on TECHWR-L, but it seems to
be a common phenomenon when people try to define a field's most fundamental
terms.
"Document" is a word that we freely redefine to suit what we want to talk
about. For example, some people want to talk about files that are stored
inside a computer and represent a viewable or printable text. They call
these files "machine-readable documents" without contradicting themselves.
If you want to speak only about the texts in their human-viewable format,
then indeed it would be a self-contradiction to speak of one of these as
"machine-readable".
So here's what I suggest: think of some propositions that you want to say
about documents. Then just define "document" so that these propositions
are true. Just be aware that, as with all the other definitions, yours
will pick out a somewhat idiosyncratic piece of the world that you want to
talk about.
Another strategy is to identify several different things that many people
have found useful to talk about, and for which they have used the word
"document". For some purposes, people might want to make statements about
credit cards, video cassettes, CAD drawings, paintings, books, billboards,
word-processing files, and the like by abstracting away their
differences--or rather, for some purposes, people might want to think about
what those all have in common. For other purposes, certain differences
might be more important to think about, resulting in narrower categories.
By the way, I believe the above approach to definitions has uses far
beyond, say, inventing the job description of various Technical Writer
positions. I spend a lot of time on many projects probing people to
understand the concepts they use. This information is important both for
putting definitions into a glossary, but to understand what I'm writing
about.
In requirements work, one very often has to take the approach of
distinguishing at a finer level of detail than most people
do--distinguishing multiple senses of a word in use, or even completely
abandoning the word because what people mean by it is at the wrong level of
abstraction. An interesting article about an example of this is "'Calls
Considered Harmful' and Other Observations: A Tutorial on Telephony", by
Pamela Zave. I first found it at her web site, at:
I'd give the full URL for the article, but I can't seem to access the site
right now. The article is somewhat technical and abstract, but it's about
the sorts of definitional problems that come up in trying to describe what
happens in telephone networks. She says that the concept of "call" just
doesn't map tightly enough to the activity of the equipment in a telephone
network for purposes of describing requirements for software to control
that equipment.
One of my favorite examples of introduced terminology in the paper is
"voice path": the set of equipment and cables that, for the moment, can
carry a signal from one place to another. The job of switching software is
to create and destroy these voice paths according to a number of complex
rules.
People who write technical documentation of any sort, not just
requirements, often have to wrestle with this sort of problem.
Notice, by the way, that "call" makes a sufficiently fine-grained
distinction to be useful to users of the telephone network (i.e. people
like you and me who "call" each other on the telephone). But it might not
be sufficiently fine-grained for people who operate software to diagnose
problems in the network. Thus the parallel with the broader and narrower
definitions of "document".
My own extremely brief tutorial on how to write a definition is at:
