3 ms·

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

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

graycat 11y ago
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.
- prof_hobart 11y ago
  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.
  - graycat 11y ago
    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?

graycat 11y ago

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.

prof_hobart 11y ago
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.
- graycat 11y ago
  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?