Other Professional Writing - Writing for Computer Science - page 181

easily fixed bugs and omissions in the browser-based interface, and “a good reason
to never buy that product”. I agree—the writing style suggests lazy, poorly managed
software development.
Indeed, as a general rule, if a reader does not understand why a system is con-
structed in a certainway or follows certain principles, it may be impossible tomaintain
it or use it. Documentation is not a substitute for good design and sensible decision-
making. It describes what you have done, not what you should have done. Aim to
generate the documentation that teaches the reader and leads them to share your
understanding. And volumes of documentation that are too large may be unusable;
only write documents that you expect will be read.
Other Problem Areas
Prominence . Often, a reader will fail to notice the main point of a document, or will
miss elements such as actions they need to take or questions that the author wants them
to address. A common cause is that the author, who may have written the document
with great care, somehow expects the reader to spend the same effort. Instead, though,
the reader may just glance through, looking at no more than headings and a few
sentences. 2 While not all readers are so slapdash, some will be, and the skill of
communication is toworkwith the behaviour of readers, not to expect them to change.
Thus it is the author's job to make sure that key messages are conspicuous to
even a casual reader. In a research paper, the standard structure guides the reader to
the main lessons, but, in other documents, the author must create this prominence
explicitly. Careful use of elements such as bold text, bullets, and repetition of themain
statements ensures that the reader sees the material that you want the reader to see.
Jargon . Jargon was mentioned earlier in this topic, but is more of an issue in gen-
eral professional writing than in academic contexts because there may be a greater
mismatch in expertise between author and audience.
It is all too easy for a technical description to degenerate into a streamof acronyms.
The SRSmodule uses theMDDandQDDsubsystems tomanageXDL records
via the CRS, with XMOP, DND, and a DNOF interface. On QVID failures
the module relies on QTS2.1 and XNS.
Mathematics is a form of jargon. Use mathematical notation for mathematical con-
cepts, but consider the audience. Translating math into text won't help people who
aren't familiar with the ideas, or who aren't accustomed to mathematical thinking.
2 One of my colleagues was notorious for never reading past the first ten lines of an email—and
then pleading ignorance of whatever the bulk of the email said. This included reminders to update
his password (he lost access to email on several occasions) and once, catastrophically, an email
from a travel agent advising of changes to flights.