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 are, if you were to ask an professional technical writer about resources for technical writing, they’d point you to a few text books on technical communication or papers or blog posts from people in the industry. Technical writing also has serious consequences. If a manual for a missile has mistakes, it could cost thousands of dollars or thousands of lives. Stephen King’s advice isn’t quite as helpful in such perilous situations.
Writing about technology, I think, is closer to what the author is actually pursuing here—and most tech blogs better fit this classification than technical writing. Writing about technology is more free form, more whimsical, full of opinion, intimations of possible approaches or solutions but not hardened proceedural documentation.
It might seem a bit pedantic to make such a distinction, but I would really love it if more people honored it. For instance, this article was a bit of false advertising, since I thought it’d be about technical writing in the professional sense (i.e. writing documentation) and not about writing about technology in a more casual, opinionated way. It’s similar to the distinction between programming and software engineering—they’re quite distinct pusuits, even though the tools and techniques considered overlap.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 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.
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.
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.
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.
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.
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.
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.
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.
I am surprised that someone who claims to have been an avid reader writes so poorly. Consider, for example,
"Fast-forward to the last year of school. I’ve started writing. It was nothing special really, short fictional stories there and there."
The author's tense is muddled, and I have no idea what "there and there" means. Better would be
"Fast-forward to my last year of school. I started writing. It was nothing special really, just some short stories."
There were a few instances where the author should have used "I" rather than "I've". In fact, I would encourage this author to avoid such contractions altogether.
The goal of writing at least one article a month is laudable, but this author should work on writing craft fundamentals. Perhaps a book like The Elements of Style would help. Even better would be a tutor or coach.
> There were no recommendation engines of course so I went through everything, itching to consume experiences left behind by humanity. Sounds like an addiction, right? Well, it kinda was.
Well, there kind of were. I doubt you would end up reading The Hobbit, The Three Musketeers and Sherlock Holmes purely by accident. The idea that the best content bubbling to the top of the popular consciousness is merely a product of modern ML recommendation engines is for the birds.
« Kids certainly don’t give a damn about them either. »
Well I guess it depends on how you educate them.
While I’m here eating my (late) breakfast, both are in their room reading.
They are 9yo (10 next spring). My son is finishing season 2 of Erin Hunter’s warriors (he loves cat) and my daughter finally catch up on Harry Potter and is reading no2 (they are not allowed to see the movies until they read the book)
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%), or even smaller minorities (3-10%) don't make a general statement "weird", at worse they make it not exhaustive.
(...) Conducted by psychologist and professor Jean Twenge, the study finds that the reading decline among American teens is worse than expected. In 2016, only 16 percent of high school seniors reported daily reading of a book or magazine. Roughly 40 years ago, 60 percent of high school seniors did the same.
(...) About a third of 12th graders also said they had not read a book or e-book for pleasure in the last year — which is about triple the number who said so in the 1970s.
Not much better for adults:
(...) The share of men reading for pleasure on any given day fell from 25 percent in 2004 to 15 percent in 2017, a drop of nearly 40 percent. The decline among women was a more modest 29 percent, from 31 percent in 2003 to 22 percent in 2017. The survey data shows declines in leisure reading across all age levels.
(...) Between 2003 and 2016, the amount of time that the average American devoted to reading for personal interest on a daily basis dropped from 0.36 hours to 0.29 hours. (...) From a breakdown of reading by income quartile, it turns out that the rich read more—but they read less and less every year. Americans in the lowest income quartile did manage to read more in 2016 than they did in 2003—a rare trend—but that’s probably a dead-cat bounce; the 2003 number was so low that it was as likely to improve as not.
>Why do you assume that American kids decline to read is a reflection of a world trend ?
Well what happens in the US, more often than not, is usually translated into a global trend too (and surely a western trend), even if it takes a decade or so (anything from fast-food to hip-hop to social trends, etc.). It's not like the US situation for that matter is unique in some way. Kids now have video games, unlimited TV options (even up to the 90s TV options were restricted), YouTube, social media, and several other things besides. Reading books is very low in their priorities.
>For example, in France, a study from 2016 shows that 78% of kids read for pleasure, with an average of 6 books per trimester.
From that number alone, and with empirical observations as a fellow European, I'm curious study and its methodology. Maybe done to promote the "good work" done by the culture or education ministry, or to make the book industry look good (to investors) or trendy (to kids)? Care to post the link to the study? Does it include comic books in that "reading"?
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 books, whether in print or eBook form.
Whether they still read social media pages, and online news, is beside the point when it comes to reading books.
>I know plenty of kids these days who read books, lots of them in fact. Often reading fiction and literature especially.
Well, since you've mentioned anecdotal evidence, all the statistics say kids read less than ever. Down to 1/4 or so of what kids in the 70s read (including eBooks).
“The children now love luxury; they have bad manners, contempt for authority; they show disrespect for elders and love chatter in place of exercise. Children are now tyrants, not the servants of their households. They no longer rise when elders enter the room. They contradict their parents, chatter before company, gobble up dainties at the table, cross their legs, and tyrannize their teachers.”
The other stupid thing about that supposed quote is that the presumption that he must have been wrong may not be justified. Socrates is thought to have lived 470-399BC. By the end of that lifetime, it would have been obvious to an impartial observer that Athenian power was fading; another generation or two later and Athens was no longer an independent power.
Yeah, it seems like the previous generation is always upset about the next generation, but they're not always wrong. Humanity has survived, sure, but most of the civilizations those sentiments were coming from haven't.
That's an interesting observation. I wonder whether a falling empire correlates to children misbehaving at schools.
I wonder whether studies were done on it in Britain or Spain, both of which you could say had empires which collapsed (though this did not threaten their whole existence).
To be clear, I'm not claiming that it does correlate... I'm only saying that you can't be sure it doesn't. It could be a selection effect, in that while it is said by everyone everywhere, we only hear from people in their cultural prime, which is just before the collapse. On the other hand, it may not be something everyone everywhere says, and it may be something that is mostly said by people in collapsing empires, in which case, it may very well be a true observation.
My main claim would just be that we don't have enough data to cite this quote (were it real) in mockery, as it is not quite as obviously wrong as it may seem from the very casual view of history.
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 are, if you were to ask an professional technical writer about resources for technical writing, they’d point you to a few text books on technical communication or papers or blog posts from people in the industry. Technical writing also has serious consequences. If a manual for a missile has mistakes, it could cost thousands of dollars or thousands of lives. Stephen King’s advice isn’t quite as helpful in such perilous situations.
Writing about technology, I think, is closer to what the author is actually pursuing here—and most tech blogs better fit this classification than technical writing. Writing about technology is more free form, more whimsical, full of opinion, intimations of possible approaches or solutions but not hardened proceedural documentation.
It might seem a bit pedantic to make such a distinction, but I would really love it if more people honored it. For instance, this article was a bit of false advertising, since I thought it’d be about technical writing in the professional sense (i.e. writing documentation) and not about writing about technology in a more casual, opinionated way. It’s similar to the distinction between programming and software engineering—they’re quite distinct pusuits, even though the tools and techniques considered overlap.