An old software joke goes, "When code
is written, only the programmer and
God understand it. Six months later,
only God.".
As a result, for continued understanding
of code, documentation, to explain the code
to a human reader, is crucial. In simple
terms, to humans, code without documentation
is at best a puzzle problem in translation
and otherwise next to meaningless. Use of mnemonic
identifier names to make the code readable
has created a pidgin-like language that is
usually unclear and inadequate.
Thus, writing documentation is crucial,
for the next time the code needs to
be read and understood, for users, etc.
Thus, net, after too many years with code
and softwarem=, I claim (big letters in sky writing, please):
The most important problem, and a severe
bottleneck, in computing is the
need for more and better technical writing.
My suggestion for some of the best models of
such technical writing are a classic
text in freshman physics, a classic text
in freshman calculus, and, at times, a
classic text in college abstract algebra
(for examples of especially high precision
in technical writing). Otherwise I suggest
Knuth's The Art of Computer Programming.
First rule of technical writing: A word used
with a meaning not clear in an ordinary
dictionary is a term, in technical writing,
say, a technical term. Then, before a term
is used in the writing, it needs a definition,
that is, needs to have been
motivated, defined precisely (maybe even
mathematically), explained,
and illustrated with examples. Then whenever
in doubt, when using the term, include a link
back to the definition. So the first rule
of technical writing is never but never use
a term without easy access to the definition.
Similarly for acronyms.
Biggest bottleneck in computing .... Sorry
'bout that. YMMV. </rant>
There is little so obscure as undocumented code.
An old software joke goes, "When code is written, only the programmer and God understand it. Six months later, only God.".
As a result, for continued understanding of code, documentation, to explain the code to a human reader, is crucial. In simple terms, to humans, code without documentation is at best a puzzle problem in translation and otherwise next to meaningless. Use of mnemonic identifier names to make the code readable has created a pidgin-like language that is usually unclear and inadequate.
Thus, writing documentation is crucial, for the next time the code needs to be read and understood, for users, etc.
Thus, net, after too many years with code and softwarem=, I claim (big letters in sky writing, please):
The most important problem, and a severe bottleneck, in computing is the need for more and better technical writing.
My suggestion for some of the best models of such technical writing are a classic text in freshman physics, a classic text in freshman calculus, and, at times, a classic text in college abstract algebra (for examples of especially high precision in technical writing). Otherwise I suggest Knuth's The Art of Computer Programming.
First rule of technical writing: A word used with a meaning not clear in an ordinary dictionary is a term, in technical writing, say, a technical term. Then, before a term is used in the writing, it needs a definition, that is, needs to have been motivated, defined precisely (maybe even mathematically), explained, and illustrated with examples. Then whenever in doubt, when using the term, include a link back to the definition. So the first rule of technical writing is never but never use a term without easy access to the definition. Similarly for acronyms.
Biggest bottleneck in computing .... Sorry 'bout that. YMMV. </rant>