News for hackers. Stuff that matters.
Re:On Technical Writing by baby on Tuesday December 31, 2019 @05:42AM (#21920140)
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 it as a "I'll read this and I'll get motivated to write".

If you came here to understand how to get into blogging: just start. Create a wordpress, and just start writing. Focus on content, not on form. After a while, you can think about a domain name, about a custom theme, or about hosting this yourself on github with hugo. But don't start with the technical parts of managing a blog, just write.

If you came here to understand how you can become a good technical writer: keep writing. Consistence over years of writing is what makes you a good writer. The ultimate technique for me is to give an interactive talk to people about your ideas, and see where your audience get stuck, where they ask questions, how different ways of explaining something get the point across.

Malcolm Gladwell does more than this: he explains an idea multiple times in different ways. If you have the page count to do this, do it. Different people need different ways of explaining.

(shameless plug: I'm writing a book on crypto https://www.manning.com/books/real-world-cryptography?a_aid=...)

Re:On Technical Writing by dnh44 on Tuesday December 31, 2019 @05:48AM (#21920158)
William Zinsser’s “On Writing Well” is also quite illuminating in regards to writing non-fiction.

https://www.harpercollins.com/9780060891541/on-writing-well/

Re:On Technical Writing by criddell on Tuesday December 31, 2019 @09:09AM (#21921067)
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.

Re:On Technical Writing by x1798DE on Tuesday December 31, 2019 @09:41AM (#21921249)
I've read it and I found it to be the most useful book on writing I've read so far, because he grounds his advice in clear linguistic principles and he is mostly not prescriptivist in his advice.

His advice about keeping an easy-to-understand sentence tree alone is worth the price of admission.

Re:On Technical Writing by abhayb on Tuesday December 31, 2019 @04:54PM (#21925029)
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 by dnh44 on Tuesday December 31, 2019 @09:35AM (#21921218)
I've read Elements of Style but not this one. I'll check it out thanks.
Re:On Technical Writing by wenc on Tuesday December 31, 2019 @02:41PM (#21924002)
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 by dnh44 on Tuesday December 31, 2019 @03:03PM (#21924231)
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 by wenc on Tuesday December 31, 2019 @03:31PM (#21924473)
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 by yesenadam on Tuesday December 31, 2019 @06:56PM (#21925651)
>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!

Re:On Technical Writing by wenc on Tuesday December 31, 2019 @07:20PM (#21925742)
I think your response comes across as unnecessarily presumptuous and sarcastic. I did read Zinsser (that was a uncharitable blow -- names are misspelled all the time). However just because I have read him does not mean I have assimilated his style or prescriptions, and even if I have, I wouldn't necessarily apply them uniformly in all of my writing.

I will admit I am expressing a subjective preference, not an objective indictment of Zinsser (I did get some value out of the first few chapters). Perhaps this dissenting opinion didn't need to be expressed because in retrospect no value was added because I didn't provide specifics myself (though I could -- I'm happy to make the case). And it's possible that I'm being unfair to the work. So in light of that, I withdraw my statement. But I still don't appreciate your sarcasm.

Re:On Technical Writing by yesenadam on Tuesday December 31, 2019 @07:32PM (#21925794)
Hi, sorry, I wasn't being sarcastic at all. I meant every word sincerely and literally, including the questions. At first I thought I had no answer for "what do folks get out of Zinnser's book specifically?", but while writing my comment I discovered that I did! Sure, it wasn't very friendly, sorry for that. I was trying to help your prose. It seemed you mostly didn't like On Writing Well for its being a book, when you got much more from courses and their feedback.
Re:On Technical Writing by wenc on Wednesday January 01, 2020 @09:41PM (#21932539)
Thanks for your clarifying response. I appreciate it. Perhaps I took it the wrong way, and for that I apologize. Happy new year to you.
Re:On Technical Writing by arvinsim on Tuesday December 31, 2019 @06:32AM (#21920331)
I would second this. I always go back to this book once in a while to review how to do non-fiction writing.
Re:On Technical Writing by grawprog on Tuesday December 31, 2019 @09:32AM (#21921202)
The article misses and fails to demonstrate the two most important parts of technical writing. Be concise and get to the point. Technical writing shouldn't be flowery and rambling. It should be focussed and say what needs to be said in as few words as possible. The article was pretty much the opposite of that.
Re:On Technical Writing by ghaff on Tuesday December 31, 2019 @09:59AM (#21921363)
Malcolm Gladwell also cherry picks research findings and observations and uses them to support some narrative. He's an excellent writer. I'm just not sure how much credence I put in many of his conclusions.

I agree with your points about blogging generally though. I've sort of gotten away from doing short/casual stuff in favor of articles for pubs. This isn't entirely a bad thing as I get more reach that way but it means I've sort of dropped shorter and more eclectic writing which I should get back to.

Re:On Technical Writing by baby on Tuesday December 31, 2019 @10:13AM (#21921463)
> Malcolm Gladwell also cherry picks research findings and observations and uses them to support some narrative

I'm mixed about this. I feel like this critic is true for any book. Books are not research papers.

Re:On Technical Writing by maxerickson on Tuesday December 31, 2019 @10:58AM (#21921882)
When a book is presented as a popularization of science, it's reasonable to expect that it is evenhanded with the evidence that is available when it is written.

Gladwell would probably end up making his books stand up better to criticism without making them any less interesting. It's fun to read about how much practice talented people have done. The problem is when you distill that down to a soundbite that sounds like a conclusion.

Re:On Technical Writing by tonystubblebine on Tuesday December 31, 2019 @11:50AM (#21922398)
I watched his Master Class and at no point does he even mention getting it right as a goal. His writing tips are only about making it interesting, memorable and shareable.

IMO, he's breaking the Spiderman rule of morality, "With great power comes great responsibility."

He's putting out intellectual versions of fraudulent ear worms without any sense of responsibility.

Re:On Technical Writing by soneca on Tuesday December 31, 2019 @06:00AM (#21920203)
Better than WordPress, I would recommend substack.com

Their business model is paid newsletters, but you can start with only free emails that is basically a free blog+newsletter with zero technical distractions.

My shameless plug, I write irregularly about writing for developers: https://writingfordevelopers.substack.com

It is not about technical writing though, but written communication.

Re:On Technical Writing by Kye on Tuesday December 31, 2019 @09:28AM (#21921176)
I like the idea of Substack, but it bothers me that they only bestow a domain mapping if you have "compelling reasons and full commitment to the Substack model."[0] This should be a simple paid upgrade. What's the point of all their talk of independence if you're stuck on a Substack subdomain when the inevitable liquidity event happens?

You can export emails and migrate paying subscribers, but all your links still point to a domain someone else controls. I don't want to have to set up a redirector just to protect myself. That's the whole point of controlling the domain.

[0] https://twitter.com/SubstackInc/status/1167162063879192576