|
T. R. Girill
Society for Technical Communication/Lawrence Livermore Nat. Lab. (retired)
[email protected]
Technical Writing: Text Revision Unpacked
Few technical texts are born in their final form. Revision, often
extensive, is almost always crucial for scientists and engineers to
share an adequate, useful technical document with others. Since students
more often see only the final result (a report, article, set of
instructions, safety data sheet) but not the process that led to it,
they can easily overlook the importance of text revision in their own
writing.
Fortunately, when computer scientists duplicate or extend in software
a complex human process like text revision, they make explicit the
otherwise invisible moves that humans covertly deploy for success.
The work of Wanyu Du's team in creating and training their R3
('Read, Revise, Repeat') text-revision program offers just such an
opportunity to see exposed the often-hidden but essential aspects
of technical text refinement (Wanyu Du, et al., 'Read revise, repeat,'
arXiv.org, 2204.03685v1, April 2022).
Four Facets of Text Revision
1. Iteration
Effective STEM writers seldom revise their drafts in one dramatic
thrust, but instead they adjust the text in several cumulative cycles
or passes. Their first draft seeds this iterative process, with each
successive pass through the text focused on different text features
or weaknesses (more on this below).
2. Review 'depth'
If the original draft is revision 0, each subsequent cycle adds
another layer of changes until the writer can find no further
improvements to make. Du's team found that their text revision
software stopped after no more than three cycles, when no further
text improvements emerged. Impatient revisers stop too soon, leaving
some helpful changes unmade, while fretful ones persist with text
changes after they have become pointless or even damaging.
3. Change intentions
Text revisions are not just random variations injected into the
draft. Each useful change aims to achieve a specific kind of
improvement or (as Du says) a 'change intention.' The R3 software,
for example, locates places in a text not yet changed on a previous
pass and then identifies the most relevant 'change intention' to
pursue at that spot. Two clusters of 'change intentions' emerged
from watching R3 work:
(a) style/fluency changes--largely grammatical or mechanical
corrections, such as adding missing or wrong articles (a, an, the)
or fixing subject/verb mismatch.
(b) clarity/coherence changes--largely adjustments in content or
text structure to focus, clarify, or better coordinate textual
assertions.
4. The revise/edit distinction
The split in change intentions that implicitly emerged from R3's
runs is actually a policy proposal for many who coach STEM writers
on how to best improve their drafts. Revision--which focuses on
the assertions that a text makes--is a primary, content-oriented
change. Some teachers enable such content improvement with the
'add, replace, move, substitute' or ARMS slogan. Editing--which
focuses on the presentation of chosen content--is a secondary
change (no need to fix the delivery of content that will be deleted
or replaced). Some teachers enable such presentation improvement
with the 'capitals, usage, punctuation, spelling' or CUPS acronym.
Whether seen through the window of R3 test runs or straight up as
a key strategy tip for any writer improving their draft, the
revise/edit distinction is one of those crucial text-improvement
insights that everyone needs to be aware of.
Modeling Revision
So how can you share these four facets of effective text revision
without intimidating struggling technical writers with a daunting,
detailed laundry list? One of the most reliable paths forward is
to publicly model helpful, iterative revision on a serious but
small-scale chunk of technical text, such as a (science fair)
project abstract or a section from a (real vendor's poorly drafted)
safety data sheet. The earlier that science students see just how
improved technical text emerges iteratively from a weak seed draft,
the more they will benefit from the foregoing techniques when they
revise their own technical writing.
[Want more background on technical writing in science class? See
http://writeprofessionally.org/techlit/handbooktoc
For a more detailed look at text design for students, see
http://writeprofessionally.org/techlit/text-engineering ]
|