Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Unsolicited Advice for Technology Writers (2014)

thefrailestthing.com

Post reply on HN
Print view View original

1–10 of 17 posts

Re: Unsolicited Advice for Technology Writers (2014)

#4

Post by farleykr »

geocrasher wrote: post #2

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.

Re: Unsolicited Advice for Technology Writers (2014)

#5

Post by cedricd »

drewcoo wrote: post #3

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

http://paulgraham.com/simply.html

Re: Unsolicited Advice for Technology Writers (2014)

#8

Post by combatentropy »

drewcoo wrote: post #3

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

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

Re: Unsolicited Advice for Technology Writers (2014)

#9

Post by combatentropy »

johncla99 wrote: post #6

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

Re: Unsolicited Advice for Technology Writers (2014)

#10

Post by dont__panic »

farleykr wrote: post #4
geocrasher wrote: post #2

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.
Post reply on HN