On Technical Writing
arturdryomov.dev
arturdryomov.dev
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.
I 100% agree that technical writing is a discipline with a specific meaning and is not the same thing as writing about technology.
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=...)
https://www.harpercollins.com/9780060891541/on-writing-well/
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.
His advice about keeping an easy-to-understand sentence tree alone is worth the price of admission.
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.
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.
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...
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!
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.
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.
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
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.
I'm mixed about this. I feel like this critic is true for any book. Books are not research papers.
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.
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.
"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.
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.
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)
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%), 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.
https://www.humanitiesindicators.org/content/indicatordoc.as...
Sources: New Yorker, WP, U.S. Department of Labor, Bureau of Labor Statistics, etc.
Especially when they fail to realize the selection bias of their commenting on a forum for curiosity-driven technology enthusiasts.
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.
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"?
Meanwhile, how about this?
https://www.thelocal.fr/20171205/french-school-children-rank...
~ Socrates
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.
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).
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.
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 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).
https://www.humanitiesindicators.org/content/indicatordoc.as...
The author lost me right there.