For my using OP in my post,
well, here on Hacker News (HN),
that is a standard abbreviation.
But, yes, good technical writing
would not do that without, say,
original post (OP) or some such.
> There was a hyperlink
Sorry, clearly that's just not
good enough since the first use
of the acronym did not have the link.
The standard in technical writing
is to take some steps to be
adequately clear on terminology
at or before the first, say, significant
or material, use of that technology
in the piece of writing.
> Google is a great source for finding things you don't know. The alternatives - explaining in every single blog post the complete set of terms that you need to understand to read it - would make for massive, unreadable posts and would be 90% useless for most of the audience it is aimed at.
Of course it would, but I've
suggested no such thing.
Instead, I was clear:
"With good technical writing, nearly anything in practical computing can be explained plenty well enough to nearly any of us."
Did I mention, my concern is
good technical writing?
I thought that somewhere in my
posts here I mentioned that
my concern was good technical
writing. To be more clear,
let me say, my concern is
good technical writing.
I want to be fully sure:
Did I say that my concern was
good technical writing?
For just what constitutes good
technical writing, I won't try
to give a course here and
will leave that
to other sources.
But, the good work in the
fields of science, technology,
engineering, and math (commonly
called the STEM fields)
has some really good examples
of good technical writing.
E.g., for science, see the
freshman physics texts by
Sears, etc. For technology,
see D. Knuth, if only his
The TeXBook. For engineering,
see, say, D. Luenberger, Optimization
by Vector Space Methods.
For math, see, say,
any of the more respected
texts for freshman calculus
going back at least 50 years.
Also see the texts of W. Rudin.
The core
problem I am addressing here
is that the technical
writing in practical computing
is way too often really badly
done with high costs for
nearly everyone involved,
really high costs.
Some of the comments here
defending the original post
are straining to defend
the bad technical writing,
making excuses for no good reason.
Let me say, likely the first
good rule in good technical writing
is to strain never but never
have undefined terms, acronyms,
and jargon; instead, on or before
the first use of any such,
have, for definitions, motivations,
discussions, examples, explanations
or at least links. E.g.,
write "Amazon Web Services (AWS)".
Just do that -- always for
the first use of the acronym AWS in
anything at all about AWS.
Just do it, always. Spend the extra
three words. Be clear. Remove
all doubt. Reassure the reader that
in the piece of writing they
just will not face undefined
gibberish. Assure the reader
that they don't need Google
searches to get prerequisites
for the piece.
Be easier to read.
For acronyms, the example
of API abbreviates both
application programming
interface and American
Petroleum Institute is
right on target -- for nearly
any three letters, there
are from several to many
three words they could abbreviate.
And, if there is no reasonable
way for the piece of writing
to be for a broad audience,
then up front say what the
intended audience and prerequisites
are.
This is dirt simple stuff. To
accept these lessons it should
be sufficient just to want
to communicate instead of intimidate.
>For my using OP in my post, well, here on Hacker News (HN), that is a standard abbreviation
And for AWS, IAM is a standard abbreviation. That's my point.
>Sorry, clearly that's just not good enough since the first use of the acronym did not have the link.
I've already acknowledged that, but one minor error - putting the hyperlink on the second use of a term that you could locate in 5 seconds in Google is hardly going to make the whole thing unintelligible is it?
>Did I say that my concern was good technical writing?
You did. And you've backed it up with pretty poor non-technical writing and a single complaint about the lack of hyperlink on the first occurrence of a single acronym that 99% of those reading an AWS technical blog would already know.
> And for AWS, IAM is a standard abbreviation. That's my point.
That point fails: HN has a much
larger and more broad audience
than AWS. Still, actually, HN should
define OP -- I still don't have
a good source to know what it means
and have been only guessing. That
AWS has a smaller audience than
HN does not excuse omitting
definitions.
Again you are assuming that
readers of that OP blog
are "99%" experienced AWS
users, and that's not good.
If the blog were only for
such users, then I should
say so.
That I could look around to
unwind the acronym, later
in the text, elsewhere on
the page, on some other
pages of the blog,
elsewhere at AWS, at Google,
doesn't excuse anything.
I mentioned some authors with
some writing that is astoundingly
technical, and there terms
are defined as I described.
Computing is awash in bad
technical writing; I should
be torqued at it, and I am;
one of the worst problems
is poor handling of technical
terminology, jargon, and
acronyms; the blog post was
an example: Either (A)
define the acronyms on or
before first usage or
warn the audience that
there are prerequisites.
Was chuckling at Herstein and Neveu above, but I must interject about Rudin here - I wasn't aware "terseness" was the largest principal component of your analysis of "good technical writing" - how about Apostol instead?
Congrats on some insight
into Rudin! He got less
terse over time. His
Real and Complex Analysis
is terrific -- hardly terse at all.
The only question
I had was, why regular Borel
measures? Sure, if I went back
and studied again where he used
the hypotheses I'd see it.
But in Rudin's favor, e.g.,
for his Principles,
it's
all there, and crystal clear,
very precise, and perfectly correct.
Yes, have to draw own figures,
at least between ears, maybe
on paper.
Students might be told that
one of the purposes of the
early material in Rudin's
Principles is to build a
really solid foundation for
discussing continuity and
uniform continuity. So, for
that, he wants compactness.
He uses that work to show that,
with continuity on a compact
set and, thus, uniform
continuity, the
Riemann (Riemann-Stieltjes)
integral exists.
Then near the end of the book
he shows that the uniform
limit of continuous functions
is continuous.
But, also he goes ahead and
shows that a function has
a Riemann integral if and only
if it is continuous everywhere
except on a set of Lebesgue
measure 0, without really
saying much about Lebesgue
measure.
I don't have much from Apostol.
I'm sure he could write a
book that competes with
Rudin's Principles and might
be easier for ugrads to read.
It happens that two weeks or
so I got out Rudin's Principles,
the third edition, and looked up
something and was struck at
just how beautifully, elegantly,
sparsely done the work actually is.
> There was a hyperlink
Sorry, clearly that's just not good enough since the first use of the acronym did not have the link. The standard in technical writing is to take some steps to be adequately clear on terminology at or before the first, say, significant or material, use of that technology in the piece of writing.
> Google is a great source for finding things you don't know. The alternatives - explaining in every single blog post the complete set of terms that you need to understand to read it - would make for massive, unreadable posts and would be 90% useless for most of the audience it is aimed at.
Of course it would, but I've suggested no such thing. Instead, I was clear:
"With good technical writing, nearly anything in practical computing can be explained plenty well enough to nearly any of us."
Did I mention, my concern is good technical writing? I thought that somewhere in my posts here I mentioned that my concern was good technical writing. To be more clear, let me say, my concern is good technical writing. I want to be fully sure: Did I say that my concern was good technical writing?
For just what constitutes good technical writing, I won't try to give a course here and will leave that to other sources.
But, the good work in the fields of science, technology, engineering, and math (commonly called the STEM fields) has some really good examples of good technical writing. E.g., for science, see the freshman physics texts by Sears, etc. For technology, see D. Knuth, if only his The TeXBook. For engineering, see, say, D. Luenberger, Optimization by Vector Space Methods. For math, see, say, any of the more respected texts for freshman calculus going back at least 50 years. Also see the texts of W. Rudin.
The core problem I am addressing here is that the technical writing in practical computing is way too often really badly done with high costs for nearly everyone involved, really high costs.
Some of the comments here defending the original post are straining to defend the bad technical writing, making excuses for no good reason.
Let me say, likely the first good rule in good technical writing is to strain never but never have undefined terms, acronyms, and jargon; instead, on or before the first use of any such, have, for definitions, motivations, discussions, examples, explanations or at least links. E.g., write "Amazon Web Services (AWS)". Just do that -- always for the first use of the acronym AWS in anything at all about AWS. Just do it, always. Spend the extra three words. Be clear. Remove all doubt. Reassure the reader that in the piece of writing they just will not face undefined gibberish. Assure the reader that they don't need Google searches to get prerequisites for the piece. Be easier to read.
For acronyms, the example of API abbreviates both application programming interface and American Petroleum Institute is right on target -- for nearly any three letters, there are from several to many three words they could abbreviate.
And, if there is no reasonable way for the piece of writing to be for a broad audience, then up front say what the intended audience and prerequisites are.
This is dirt simple stuff. To accept these lessons it should be sufficient just to want to communicate instead of intimidate.
Are we communicating now?