|
T. R. Girill
Society for Technical Comm./Lawrence Livermore National Lab. (retired)
[email protected]
Technical Writing: Text-Design Checklists Share Expertise
Checklists are a well-known, experience-backed tool for capturing and
sharing professional expertise. They have even earned a book-length
laudatory treatment in Atul Gawande's The Checklist Manifesto (Picador,
2011), which pointed out their benefits for experts as well as for
novice practitioners. Classroom-tested student-support checklists
for drafting both technical descriptions (writeprofessionally.org/
techlit/analysisgd) and instructions (writeprofessionally.org/techlit/
instructions) are freely available online as part of LLNL's technical
literacy outreach project.
Five Checklist Benefits
Checklists provide surrogate experience packaged in an easy-to-borrow
format. Text-design checklists help student writers in five related
ways:
1. They help AVOID COGNITIVE OVERLOAD by overtly itemizing important
tasks that even busy experts might overlook when drafting text under
pressure. That's how checklists help master surgeons as well as
novices perform better in the operating room. (For descriptions for
example, 'divide complex objects into parts and order the parts').
2. They DECOMPOSE COMPLEX PROCESSES into more simple steps for more
reliable execution. For example, 'visibly organize the text with
headings and lists.'
3. They help STEER USERS AWAY from tempting but bad shortcuts and
toward better, experience-based text-design alternatives. For example,
'include--do not carelessly omit--key verbal signals such as 'also'
or 'however'.'
4. They overtly RAISE TEXT-USABILITY ISSUES that struggling student
writers might not recognize on their own, hence broadening and
enriching student expertise as they practice. For example, 'introduce
comparisons and contrasts to reveal feature significance.'
5. They ENABLE ACTION--and hence skill-building exploratory practice
--in text-drafting situations where student writers might otherwise
stall and write nothing in frustrated confusion (thus, for instructions,
'make each step a visibly distinct overt command').
Self-Designed Checklist Pitfalls
College-level software engineering students are often asked to
construct their own checklists as they prepare for teamwork sessions
in which they review draft computer programs searching for flaws
and quality improvements. A recent study of 1700 student-drafted
code-review checklist questions explored just how helpful and
reliable such student-designed checklists are (Chun Y. Cong and
others, 'Assessing students' understanding and their mistakes in
code review checklists,' arXiv.org/2101.04837v1, Jan. 13. 2021).
Participants here were older students already well into a professional
college program in software quality. Nevertheless, a careful
analysis of the checklist questions that they proposed showed that
about 25% were seriously inappropriate or misguided for detecting
or correcting program weaknesses:
1. Unclear--some student-proposed checklist questions were 'too
generic or ambiguous' to actually help detect flaws within draft
code. For example, 'is the code maintainable?' does not lead to
any specific improvements in the program (like asking if a draft
text 'is revisable').
2. Irrelevant--some student-proposed questions only pertained to
run-time problems undetectable just by inspecting the program text
(like asking if a draft text is amusing or insulting).
3. Misplaced focus (inappropriate technique)--typing or spelling
errors in code are best caught with software filters, just as such
mistakes in a draft text are best caught with standard spell-check
tools.
So having students construct their own good-description or good-
instruction checklists clearly calls for another layer of
metacognitive awareness--about linguistics and learning generally
as well as about text usability specifically--that few inexperienced
young writers will possess. On the other hand, having students draft
and revise text while armed with reliable, experience-based checklists
already confirmed in other contexts shares with them the expertise
of others, which guided practice lets them gradually add to their
own skill set. And in this they follow the authentic path of
successful professionals in diverse skill-rich fields.
[For a text-design framework that places good-description and
good-instruction student checklists in context, see
http://writeprofessionally.org/techlit/usability ]
|