Technical Writing
As an experienced technical writer, I present technical information in a manner that facilitates ready assimilation and comprehension. I strive for clarity and avoid ambiguity. I am very well trained in the proper use of the English language as well as in formal logic and informal fallacies. I am also adept at recognizing and correcting amphiboly.
I have generated the full gamut of instructional literature from guidelines for product application and selection, instructions for assembly, installation, and operation to safety, quality assurance, maintenance, and troubleshooting. Deliverables have included user manuals, training materials, brochures, catalogs, data sheets, and presentation graphics. Subject matter has included architectural, ventilating, and plumbing products; modular office furniture; control systems for hydronic heating and cooling systems; conveyors and material-handling products, systems, and controls; paper-making and converting machines; commercial ovens; web-fed, multi-station, offset and ink-jet perfector printing systems; electronic medical-diagnostic equipment; automated chemical-processing systems; CNC machine tools; integrated manufacturing systems; and rocket-engine controllers and automated rocket-engine-controller testing systems.
Since virtually all of the technical writing I have done has been performed under nondisclosure agreements, I am unable to provide much in the way of actual work-related writing samples. I have, however, written, illustrated, and photographed everything on this website, with one notable exception: I did not take the photograph of the brain on the Cognitive Psychology page . . .
— and it isn't even my brain!
Avoiding Confusion
Flaws that I commonly find in technical literature that contribute to confusion include the following:
- Failure to orient the end user to the topic before delving into details,
- Disagreement in number between the subject and the predicate, especially where a modifying phrase intervenes,
- Lack of parallelism in lists,
- Abuse of words as parts of speech not proper to them,
- Misuse of the solidus (“slash”),
- Run-on sentences,
- Dangling modifiers, and
- Improper punctuation.
On Language
By its very nature, a language – any language – is a
convention consisting of a set of symbols, such as a vocabulary, and a set of rules governing the use of those symbols, such as a grammar (and, no, so-called “body language” is not a real language; it may be a mode of expression, but it is not a genuine language per se). This is true for all languages – natural languages, computer languages, mathematical, scientific, and engineering notation, symbolic logic, and so forth. The most important thing about a language is the fact that it is a convention, and what makes a convention a convention is adherence, not deviation. In order for a language to serve as an effective mode of communication, it is necessary for users of the language to adhere to its conventions. Deviation from established conventions invites ambiguity and confusion.
On Definitions
Logicians recognize five kinds of definitions:
- Lexical – established or “dictionary” definitions, which show how words should ordinarily be used. A lexical definition not only describes how a given term is normally used but also prescribes how the term normally should be used,
- Stipulative – a definition that is given for a brand-new term when it is first introduced,
- Precising – a description that clarifies the exact, intended meaning in instances where the relevant lexical definition alone may not be sufficient,
- Theoretical – the formulation of a theoretically adequate characterization of the objects to which it is applied, and
- Persuasive – a type of definition the purpose of which is to influence attitudes.
The notion of a personal “definition” of a term that is unique to the individual (e. g., “my definition” of a word versus “your definition”) is antithetical to the essential nature of language. Confusion over the difference between a definition of a term and a referent to which the term is applied, however, abounds. When one uses a term, he or she invokes a (normally lexical) definition for the term and uses the term to refer to some object under discussion. The object in question is called a "referent," not a definition. It is usually over the objects to which they refer that people disagree, not in their "definitions." An object may be the
epitome of the category to which the object belongs, but such an object is never the
definition of the term.
When something new is discovered, invented, or innovated, of course, we obviously need to have some way of referring to it, and so new terms are coined, or new definitions are added to pre-existing words. Obviously, a word can have multiple definitions. It is important to note, however, that words take on new definitions by accretion, not displacement; pre-existing definitions are retained. So, when a new definition is added to a word, the risk of ambiguity is increased.
Linguistic "Evolution"
Some people argue that the English language is constantly changing and evolving, that nothing in the language is stable. While there is some truth to that proposition, it is more important to notice that the core of the language stays the same, that the definitions of most words do not really change significantly from one generation to the next. Otherwise, it would be impossible for people to figure out from context what is meant when an individual word is used to mean something different from its established lexical definition.
To some degree, linguistic evolution may be unavoidable. Shakespearean English, for example, is practically unintelligible to us today. Yet Shakespeare died over 400 years ago. To our current, highly technological generation, it is imperative to maintain the capacity of the language to express precise things in a precise way. Professional users of the language therefore have a natural fiduciary duty to resist the impulse and pressure to give the language an "evolutionary push." Taking liberties with the language is for advertising copywriters and demagogic politicians. The dutiful technical writer, however, adheres to the established conventions of the language, to the lexical definitions of words, and to the use of words as parts of speech that are proper to them.
Layout & Design
The layout and design of a page is integral to the presentation of information. When it comes to the topic of layout and design, many technical-writing instructors simply tell their students to make the page “pleasing to the eye,” and they leave it at that. That kind of advice seems awfully subjective, and it provides utterly no guidance for precisely how to make the page “pleasing to the eye.”
It is often assumed that graphic displays are acquired directly into the mind wholly intact, much like importing a raster image into a document, but it doesn’t work that way at all. The retina and primary visual cortex are not conceptual organs; they do not recognize what they are beholding or comprehend the slightest significance of anything presented to them. Yet all of the information presented in written and graphic form must be processed through the retina and visual cortex before it is received into working memory, that is, the presently conscious mind. So, it is beneficial to have some understanding of how the retina and visual cortex process incoming visual data in order to design the presentation of information judiciously.
A very complex series of analyses occurs, beginning in the retina and in the primary and secondary areas of the visual cortex in the occipital lobe of the brain, and proceeding to additional processing areas in the temporal lobes. These analyses include detecting light and dark, color, contrast, motion, feature and object recognition, and a host of additional attributes. In the retina and in the visual cortex, there is a dedicated neural synapse for detecting each of these aspects of the visual array. These analyses occur even before the mind becomes aware of what the eyes are looking at, which is to say that the process is entirely subliminal. Ultimately the results of this analysis are filtered when transferring data from sensory memory to working memory in accordance with the perceiver's attentional focus. Yet it only takes a fraction of a second for the mind to recognize and respond to what the eyes are looking at, which attests to how rapidly this analysis occurs.
When reading a document or attending a presentation, the end user’s conscious mind is normally focused on the content and meaning of the message and not specifically on the design features of the visual display. Yet the eye and brain have to process every visual element presented to them on a page or screen, including those elements that are filtered out before reaching working memory. The more complex the graphic display, the more work the eye and brain have to do to process it, which results in increaseed eye strain and visual fatigue, which adversely impact the tolerable duration of concentrated attention. So, for the end user's sake, it behooves the technical writer or instructional designer to simplify the graphic display as much as possible and to cater to the sensibilities of the eye and brain.
I take a design approach based on cognitive and Gestalt psychology, and I apply principles of
Design for Effective Communication of Technical Information (DECTI). I eliminate graphic elements that are not essential. I utilize visual mass, grouping, alignment, and spacing to enable the content of the message to organize itself visually and to optimize space utilization. These techniques are especially helpful with very complex tables in which horizontal space is at a premium. Though such a “hard-core” approach is not needed for the easy cases on certain pages, I design the whole document based on the hard cases, and the easy cases will fall into place. That way, the entire document has a consistent “look and feel,” and the graphic treatment speaks with a professional corporate voice. By no small coincidence, objectively speaking, this approach also tends to be “pleasing to the eye.”
