I'm just saying that there is bad technical writing, that there's no good reason for it, and that it's darned costly.

If the that OP blog post was just for existing, old AWS customers, then find, good, okay, sure, of course, but make that point clear, up front.

Else, Jeff Bezos, I'm building a Web site; I've got the production quality, reasonably high capacity, scalable software written and running; HP has offered me servers initially for free; I plan, intend, and hope my Web site becomes a big thing; I should consider a cloud instead of my own server farm; AWS should be a candidate; I'm close enough now to going live that I should be looking into AWS; I read the OP to get started; I came away from that post and its poor technical writing torqued and wanting to set aside AWS even if I was offered it for free (for me to work through enough more AWS bad technical writing for my Web site would be much more costly than free, making a free service still too costly), that's a bad situation for Jeff Bezos, Amazon, AWS, and me.

There's a lot of absurdly bad technical writing in computing for absurdly poor reasons with absurdly high costs. I should have been torqued decades ago; I should be torqued now, and I am.

I just want better technical writing, in particular to save my time, effort, and money. For this instance, the blog just needed a common statement about "Who this information is intended for".

For AWS to put out information about their services with bad writing that torques off a highly serious and experienced software developer is bad business for both AWS and me.

I am just objecting to the costly bad technical writing. Simple. Should not be difficult, complicated, or controversial.

You seem to be mistaking your lack of knowledge of a particular set of technologies with bad writing. I read it and it was an absolutely clear article to me.

I want an article explaining how Amazon's API gateway works, not what all of Amazon's services are, what API gateways are, what REST is etc. There's already plenty of those out there. Not every article needs to explain every concept from scratch.

They even have a link to a page on what IAM is for those who don't know (admittedly it's not on the first mention, but that hardly makes the entire article badly written).

The issue here is not me but some bad technical writing.

The OP failed to explain that a prerequisite to reading the post was being a long time AWS user. Then, the OP was bad technical writing. Done. QED.

Without such a warning about prerequisites, the undefined acronym was bad technical writing.

> your lack of knowledge of a particular set of technologies

That whole concept is big mistake common in computing. The "technologies" in question are, for at least a good first description, just dirt simple with meager prerequisites.

None of us in computing should try to carry the whole pile of simplistic trivia around between our ears. For a related lesson, after a while in academics, it becomes obvious that only fools try to carry the whole research library around between their ears -- the lesson is much stronger for the less deep, less good material in practical computing.

With good technical writing, nearly anything in practical computing can be explained plenty well enough to nearly any of us.

I don't have a relevant "lack" of anything in computing.

It wasn't undefined. There was a hyperlink to a page all about it.

You failed to explain what OP meant, and didn't explain that your comment was aimed at people who knew this kind of terminology. Does that make your comment bad writing?

No one is suggesting that people should carry every bit of technology around in their heads. 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.

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.

Are we communicating now?

>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.

Simple.

>Still, actually, HN should define OP -- I still don't have a good source to know what it means and have been only guessing.

So it's HN's fault, not yours, that you didn't define a term that you chose to use?

And you're using a term that you don't know what it means?

> I should be torqued at it, and I am

What is "torqued" meant to mean in this context? I know what torque means, but it makes no sense when applied to this sentence.

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.

On elegance, Neveu is my favorite.