Hacker News new | past | comments | ask | show | jobs | submit login
Unsolicited Advice for Technology Writers (2014) (thefrailestthing.com)
26 points by thomasjbevan 4 days ago | hide | past | favorite | 16 comments

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.

CC-BY-ND-NC licence, specifically.

11. Don't refer to anything as simple just because it is simple to you.

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.

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.

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.

A post three days ago highlighted comments here that had the phrase "why not simply": https://news.ycombinator.com/item?id=27415725

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

Thanks. I was thinking the same thing. The language is hard to read.


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

Most unordered lists like this should be numbered so you can later refer to the points by number.

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.

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.

"The craft of scientific writing" is a great book btw.

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.

It isn't for that kind of tech writer. It is "for pundits, journalists, bloggers, and assorted scribblers who write about technology".

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact