[HN Gopher] Unsolicited Advice for Technology Writers (2014)
___________________________________________________________________
Unsolicited Advice for Technology Writers (2014)
Author : thomasjbevan
Score : 25 points
Date : 2021-06-10 12:25 UTC (10 hours ago)
(HTM) web link (thefrailestthing.com)
(TXT) w3m dump (thefrailestthing.com)
| geocrasher wrote:
| 11. Don't refer to anything as simple just because it is simple
| to you.
| combatentropy wrote:
| A post three days ago highlighted comments here that had the
| phrase "why not simply":
| https://news.ycombinator.com/item?id=27415725
| farleykr wrote:
| The article could do with more substance overall but this is
| one of my biggest pet peeves and I appreciate it being pointed
| out. I think the tendency of some tech articles/tutorials to
| refer to things as simple is part of the faux-friendly-jokey
| attitude that a lot of tech writing adopts--especially on sites
| like Medium. That and emojis and gifs. I tend to close an
| article/tutorial as soon as I see an emoji or a gif.
| dredmorbius wrote:
| If you're looking for substance, the article itself is from a
| related blog on technology, and there's a book compiling ~100
| highlight articles from that. The short list is just that: a
| short list.
| dont__panic wrote:
| At the very least, gifs should only play when you click them
| in an article that I'm actually expected to read. Do other
| people actually enjoy reading static text with a giant low-
| resolution flickering image on screen next to it? It's just
| so distracting to me. Seems like Developer Advocates love to
| do that sort of thing in blog posts.
| rcpt wrote:
| "The craft of scientific writing" is a great book btw.
| drewcoo wrote:
| > in no particular order ...
|
| And what follows is an ordered list. Of mostly unsubstantiated
| nonsense explained in bloated language. That opposite of what I'd
| expect from good tech writing.
|
| Is this a satire? It feels like something out of McSweeney's.
| watwut wrote:
| Every list is ordered. "No particular order" means "dont think
| they are ordered by importance".
|
| It is list of authors pet peeves, stuff he would like writers
| to follow. I did not found the language bloated, it was easy to
| understand.
| projektfu wrote:
| Most unordered lists like this should be numbered so you can
| later refer to the points by number.
| combatentropy wrote:
| > And what follows is an ordered list.
|
| Isn't it just a numbered list? You can number things, but that
| doesn't mean it's in order of importance, just the order it
| popped into the writer's head.
|
| > Of mostly unsubstantiated nonsense explained in bloated
| language. That opposite of what I'd expect from good tech
| writing.
|
| I agree. At first I thought this was for "tech writing" in the
| sense of user manuals. But this is for journalists. And it's
| more just a vague rant.
| munificent wrote:
| The headline is confusing, but I think the author means advice
| for "people who write about technnology", not "technical
| writers" the profession. The second sentence is pretty clear on
| the intended audience.
| cedricd wrote:
| Thanks. I was thinking the same thing. The language is hard to
| read.
|
| http://paulgraham.com/simply.html
| johncla99 wrote:
| Wait...I was a tech writer for 20+ years at a major software
| developer. To me, a tech writer is someone who documents apps or
| APIs. If true, I don't see what this article has to do with tech
| writers.
| combatentropy wrote:
| It isn't for that kind of tech writer. It is "for pundits,
| journalists, bloggers, and assorted scribblers who write about
| technology".
| dredmorbius wrote:
| Desplite the original title (HN's clarified it), the topic isn't
| _technical writing_ as might be presumed, but _writing on
| technology_ , and mostly the sort of pie-eyed, overly credulous
| and bombastically optimistic variety that's often found. Even,
| occasionally, on the pages on Hacker News.
|
| The list is a set of tired tropes which occur with some
| frequency.
|
| It's short. There are links to expanded discussion. The context
| is a 10-year blog of the author's on the larger topic of
| technology and technological criticism, and yes, there's a book,
| pay-what-you-can, CC-licensed: https://gumroad.com/l/CWRfq
|
| I might have added, substituted, or amended a few items, most
| especially that there is actually something of a _history_ and
| _philosophy_ of technological criticism, but that 's me. The
| latter point _is_ picked up in the blog at large and the book.
|
| For an item I very nearly passed over on account of its original
| title, this is actually an intruiging find. Thanks to
| thomasbjeven for turning it up, and L.M. Sacasas for writing it.
___________________________________________________________________
(page generated 2021-06-10 23:03 UTC)