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

On Technical Writing

arturdryomov.dev

Post reply on HN
Print view View original

31–40 of 45 posts

Re: On Technical Writing

#31

Post by kaycebasques »

voidhorse wrote: post #28

This article, like many on “technical writing” conflates techincal writing and writing about technology . In my estimation, they’re two different things. Technical Writing is a profession with a massive set of practices, relatively well-prescribed goals, and a long history. It’s a discipline that has almost nothing to do with Stephen King and Strunk and White—though of course these sources might be applied. Chances a…

My guiding goal as a practicing technical writer is how do I transfer knowledge as efficiently as possible? For that reason I think it’s a skill that is applicable to anyone whose job depends upon a lot of collaboration, which is why I think we see the topic come up somewhat frequently here on HN.

I 100% agree that technical writing is a discipline with a specific meaning and is not the same thing as writing about technology.

Re: On Technical Writing

#32

Post by blululu »

voidhorse wrote: post #28

This article, like many on “technical writing” conflates techincal writing and writing about technology . In my estimation, they’re two different things. Technical Writing is a profession with a massive set of practices, relatively well-prescribed goals, and a long history. It’s a discipline that has almost nothing to do with Stephen King and Strunk and White—though of course these sources might be applied. Chances a…

Agreed. I too would have enjoyed a discussion of the challenges of technical writing. Especially since I feel like it is becoming increasingly common forego hiring technical writers and have engineers write documentation. Which is a shame because a lot of people rely on documentation for their work and inconsistent/low quality documentation really hurts a technical product.

Re: On Technical Writing

#33

Post by aspaceman »

coldtea wrote: post #18
aspaceman wrote: post #4

Earlier quoted context omitted.

"Kids these days" never really goes away huh? Funny how smart phones and social media will be our version of that.

> "Kids these days" never really goes away huh? And it's seldom wrong either. Kids do have different behavior in different ages. Whether that's good or bad is another thing (in some things it's bad, in others are good). But culture, habits, etc, are not the same blob of sameness for centuries. Kids in 1950 are different than kids in 2020 or kids in 1900. In this particular case, indeed, kids these days seldom read bo…

It’s frustrating because it’s based on anecdotal evidence and preconceptions. It also defaults to the assumption that all change is bad.

I know plenty of kids these days who read books, lots of them in fact. Often reading fiction and literature especially.

Re: On Technical Writing

#34

Post by wenc »

dnh44 wrote: post #8
baby wrote: post #7

This article is actually quite empty, it starts like it is going to be about how to write good technical content, then becomes an auto-biography, then becomes an article on how one can get started blogging, then just end abruptly with some statistics that probably nobody cares. So if you came here to know how to write, Stephen King wrote a book "On Writing" that is quite interesting and mostly reads like a novel. See…

William Zinsser’s “On Writing Well” is also quite illuminating in regards to writing non-fiction. https://www.harpercollins.com/9780060891541/on-writing-well/

Curious, what do folks get out of Zinnser's book specifically?

The title has made its rounds in tech circles for a while, and I've read it. Not to be an HN contrarian, but apart from a few tips that it offers toward the beginning, it's actually a pretty dry read and does not itself, in my opinion, reflect good writing (the first few chapters are OK, then it goes downhill from there). I read a lot and unfortunately I wouldn't say Zinnser's book is a piece of writing I would admire.

I've taken IRL creative writing courses since, and I gotten a lot more out of these, because not only did I manage to receive instruction in technique, I also received continuous direct feedback in the form of workshops and instructor critique.

Re: On Technical Writing

#35

Post by OpenCoderX »

voidhorse wrote: post #28

This article, like many on “technical writing” conflates techincal writing and writing about technology . In my estimation, they’re two different things. Technical Writing is a profession with a massive set of practices, relatively well-prescribed goals, and a long history. It’s a discipline that has almost nothing to do with Stephen King and Strunk and White—though of course these sources might be applied. Chances a…

You are not being overly pedantic, writing about the maintenance procedures and goals when maintaining nuclear medical equipment is technical writing, a Neil Stephenson novel is not.

Re: On Technical Writing

#36

Post by dnh44 »

wenc wrote: post #34
dnh44 wrote: post #8

Earlier quoted context omitted.

William Zinsser’s “On Writing Well” is also quite illuminating in regards to writing non-fiction. https://www.harpercollins.com/9780060891541/on-writing-well/

Curious, what do folks get out of Zinnser's book specifically ? The title has made its rounds in tech circles for a while, and I've read it. Not to be an HN contrarian, but apart from a few tips that it offers toward the beginning, it's actually a pretty dry read and does not itself, in my opinion, reflect good writing (the first few chapters are OK, then it goes downhill from there). I read a lot and unfortunately I…

I feel that it helped me learn to write better business emails, by getting me to focus on writing clearly and concisely.

I’d have to refer to the book to be able to comment on the specifics of the advise though.

I also remember the beginning of the book being more interesting but perhaps the beginning was just more relevant to me.

Re: On Technical Writing

#37

Post by wenc »

dnh44 wrote: post #36
wenc wrote: post #34

Earlier quoted context omitted.

Curious, what do folks get out of Zinnser's book specifically ? The title has made its rounds in tech circles for a while, and I've read it. Not to be an HN contrarian, but apart from a few tips that it offers toward the beginning, it's actually a pretty dry read and does not itself, in my opinion, reflect good writing (the first few chapters are OK, then it goes downhill from there). I read a lot and unfortunately I…

I feel that it helped me learn to write better business emails, by getting me to focus on writing clearly and concisely. I’d have to refer to the book to be able to comment on the specifics of the advise though. I also remember the beginning of the book being more interesting but perhaps the beginning was just more relevant to me.

Since you brought up writing business emails...

For writing emails and structuring presentations I've found the Pyramid Principle [1] to be quite practical. (apparently McKinsey consultants are trained to do this, along with stuff like MECE, etc. Whatever we think the actual abilities of McKinsey consultants may be, they are generally pretty good at making million dollar PowerPoint decks :)

The idea is simple:

1. Start with the answer first.

2. Group and summarize your supporting arguments. (not more than 3)

3. Logically order your supporting ideas. (chronology, structure or priority)

The article below makes the point that "this “top-down” structure is counter-intuitive for many of us with a scientific or engineering background", but I've observed it is exactly this structure we must adopt for impactful business writing.

[1] https://medium.com/lessons-from-mckinsey/the-pyramid-princip...

Re: On Technical Writing

#38

Post by JeanMarcS »

minblaster wrote: post #26
coldtea wrote: post #17

Earlier quoted context omitted.

> what a weird statement by the article's author I can never understand this reasoning. The statement by the article's author covers 80% or more of kids, who mostly don't read (and 90% or more reads zero to one book a year). It's like someone noting that "people have one nose" and somebody arguing, "This is such a weird statement to make, my neighbour, who was on a traffic accident, has none"! Extreme Outliers (1-2%)…

Yep, many think their single n=1 counterexample dismantles the truth of a general trend. Especially when they fail to realize the selection bias of their commenting on a forum for curiosity-driven technology enthusiasts.

Why do you assume that American kids decline to read is a reflection of a world trend ?

I’m sorry but those numbers are not true everywhere.

For example, in France, a study from 2016 shows that 78% of kids read for pleasure, with an average of 6 books per trimester.

That’s not that bad I guess, but hey, what do I know, I am not American...

So sorry but no, my example is not an n=1. But more a n= 78% of around 70M persons country.

Re: On Technical Writing

#39

Post by abhayb »

criddell wrote: post #11
dnh44 wrote: post #8

Earlier quoted context omitted.

William Zinsser’s “On Writing Well” is also quite illuminating in regards to writing non-fiction. https://www.harpercollins.com/9780060891541/on-writing-well/

Have you read Steven Pinker's Sense of Style ? https://stevenpinker.com/publications/sense-style-thinking-p... I was thinking about reading it but it's hard to find reviews of the book that don't include praise or criticism of Pinker's other work or the author himself.

Pinker made it easy for me to slip into my own thoughts about writing, how I currently write, and how I would like to write in the future. Just for that I thought it was worth it. However Pinker has Opinions about writing rather than just suggestions. Be prepared to disagree with what he says and how he says it. I suspect he would be glad for you to do both.

Re: On Technical Writing

#40

Post by yesenadam »

wenc wrote: post #34
dnh44 wrote: post #8

Earlier quoted context omitted.

William Zinsser’s “On Writing Well” is also quite illuminating in regards to writing non-fiction. https://www.harpercollins.com/9780060891541/on-writing-well/

Curious, what do folks get out of Zinnser's book specifically ? The title has made its rounds in tech circles for a while, and I've read it. Not to be an HN contrarian, but apart from a few tips that it offers toward the beginning, it's actually a pretty dry read and does not itself, in my opinion, reflect good writing (the first few chapters are OK, then it goes downhill from there). I read a lot and unfortunately I…

>a pretty dry read

I'm not sure what you mean, except you didn't enjoy his style? Gee, he seems the opposite of dry to me–a very warm, friendly, human voice. If you think he's pretty dry, who in the field do you prefer?

I don't think you can have read Zinsser. You misspell his name, and it's hard to believe your sentences are those of someone who's heard his message:

"Not to be an HN contrarian, but" – this adds nothing. The reader of On Writing Well learns to cut every unnecessary word.

"it's actually a pretty dry read and does not itself, in my opinion, reflect good writing" says unclearly in 16 words what could be said clearly in a few. Cut "actually", "in my opinion" and "itself". Does not reflect good writing – do you mean "it's not good writing"? i.e. "it's bad writing"? I'm not sure what saying a book "doesn't reflect good writing" means, but seemingly something other than its not being written well, or you would have said so, the reader assumes.

"unfortunately I wouldn't say Zinnser's book is a piece of writing I would admire." Again, the head spins, although what you're trying to say seems simple. If it's "I don't admire it", why not say so? If something else, say that. Simplicity! Etc.

I encourage you to give him another go!

Post reply on HN