|
T. R. Girill
Society for Technical Communication/Lawrence Livermore Nat. Lab. (retired)
[email protected]
Technical Writing: Text Clarity for Impact
Based on empirical analysis of actual STEM conference papers, Portuguese
computer scientist Carlos Baquero recently offered two text quality
insights for working STEM professionals that also provide good guidance
for students just mastering technical literacy (Baquero, 'Picking
publishing targets,' Communications of ACM, March 2022, 65:3, 10-12,
DOI: 10:1145/3510545):
1. Reviewers of a technical draft 'are more consistent in detecting
weaker papers than in agreeing on the best ones'--your writing flaws
will seal your fate, and
2. 'Perception of paper CLARITY was the best predictor of future
paper impact.'
This central role of clarity for impactful text can help focus the
efforts of students who impatiently do not yet see the value of
bothering to construct clear (as well as accurate) technical text,
along with those just learning the techniques that make a STEM draft
more clear for its audience.
CCSS Clarity Support
Fortunately, the Common Core State Standards (CCSS) for English
Language Arts explicitly embrace this central value of clarity
when articulating the text skills that students should practice and
then display at each grade level.
Every grade-level band (e.g., W11-12.2 for high school) includes TWO
explicitly labeled components, each a necessary condition for
generating clear technical text. One, of course, is providing
readers with appropriate STEM content (e.g., W11-12.2B)--
'develop a topic thoroughly by selecting the most relevant facts
...concrete details...and examples.'
The other component is deploying appropriate PRESENTATION of that
content (e.g., W11-12.2A)--'introduce a topic...organize complex
ideas, concepts, and information...to create a unified whole.'
Thus CCSS itself makes explicit that clarity is a composite virtue
of technical text--the writer must provide relevant, specific
information, but also must structure that information in a way
that makes sense for the intended audience (which might be other
experts, the broader scientific community, or the public at large).
The Programming Parallel
Further authentic support for helping students embrace the twin roots
of technical clarity comes from the clean-code/clear-code distinction
in software engineering.
No one wants a computer program that fails to run or that yields
erroneous or inappropriate results. But as software engineer
Yegor Bugayenko notes, 'clean [flaw-free] code provides a solid
foundation but it's not enough for exceptional code' (Bugayenko,
CACM Blogs, March 12, 2020). As a colleague or user, 'if you
don't understand the sparkling clean code, it's difficult to work
with' and 'there's a risk you'll misinterpret something' important
while doing further work.
Just as with all technical text that is crafted to be shared and
used by others, the extra work to achieve reliable, helpful
presentation is vital along with technical adequacy for full
success. 'Ultimately, clear code is easy to understand, modify,
and maintain. If you were taking over programming for software,
wouldn't you want the code to be all of the above? Of course!'
(Bugayenko, p.2). So textual clarity, once again, is not just
for school but for real life with its real demands.
The extra effort required to engage student writers with text
framing, cues, structure, and other clarity-enhancing text features
(the 'A' band in every CCSS grade-level standard) is justified by the
expectations and needs of their future colleagues throughout
science and engineering (and ultimately by the public benefit that
results). Clarity promotes impact, as Baquero discovered.
Besides these universal issues, some ESL students may also need
extra English-specific support to achieve useful text clarity--
often concerning proper pronouns, English articles ('a, an, the'),
or common science idioms ('above all,' for example)--for which
the links below offer some focused resources.
[Want more background to help ESL students with technical writing?
See http://writeprofessionally.org/techlit/esl-issues
For more suggestions to improve the helpfulness of student text
see http://writeprofessionally.org/techlit/usability ]
|