Ask HN: How to level up your technical writing?
Hi fellow HNers!
I have a fairly strong background in cloud system and application architecture. However I feel that I’m sometimes limited by my technical writing skills to communicate my ideas and concepts. Any advice on how to take ones technical writing skills to the next level?
I’m willing to do what it takes, being online courses, contributing to OSS process work or what else you might suggest.
Looking forward to tap into the HN hive mind on this topic!
Thanks, Max
161 comments
[ 2.9 ms ] story [ 229 ms ] threadJoseph M. Williams, Style: Ten Lessons in Clarity and Grace.
An old edition is fine. There are many editions with slightly differing titles (Toward Clarity and Grace, The Basics of Clarity and Grace), all of them are fine. Get the cheapest or fastest to deliver or whatever. Don't think about which one to get.
The other great book about writing is Thomas&Turner's Clear and Simple as the Truth. It teaches Classical Style, which is less fitting to technical documentation, as the authors discuss themselves.
The most effective way to improve your writing is through improving your reading.
I’m a literary nerd as well as a technologist, and will tell you it’s easy to spot an English Lit graduate by their universally good documentation skills. Not because they use fancy words, or exotic expressions, because they use simple deadpan and well measured (never crowded) sentences. These tend to always write as though they’re explaining to an intelligent child (with a pleasant unassuming and direct simplicity.)
I’m sure you have read those great todo articles on medium or log rocket or whatever.
The problem with citing good professional documentation is that this is usually or inevitably taken on by a team, so docs are really a standard of a good editor.
The problem with stuff in the wild is it can be too bloggy or conversational.
What you need is awareness and purpose. Stop reading junk as soon as you identify it (skim junk for take always ;).
Cherish and reread somethings that “speak to you.”
Ironically, the best technical documentation is dry and to the point (without sounding as though generated from already inadequate code comments [glare].)
Edit out sarcasm, sentiments, and unnecessary references or language.
Explain what is happening, show an example and stop. You’ll do fine!
Do read one of those boring grammar/punctuation books. Just being aware of good sentence form will make you a better writer.
I did all this stuff over a decade ago, so I don’t have a link off hand.
Here's some technical writing courses: https://developers.google.com/tech-writing
And here are some examples of good writing: https://news.ycombinator.com/item?id=31630915
It’s no different than writing code or writing a book. It takes time, iteration, and focus.
Personally happy to review a doc or two and provide feedback if that is helpful. I run a docs site for my company.
And "Bugs in Writing", which I've been pressing into people's hands for twenty years now. https://www.amazon.com/BUGS-Writing-Revised-Guide-Debugging/...
About a year or so ago I read through a bunch of that course and it seemed like it would be okay for someone who is new to writing in a business setting. But generally the summary was said: be concise as possible while still getting the message across to the appropriate audience.
Looking at it again, the "organizing large docs" is pretty good. https://developers.google.com/tech-writing/two/large-docs#pr...
"Choose a heading that describes the task your reader is working on. Avoid headings that rely on unfamiliar terminology or tools."
Products on Amazon even get the Hug of Death™.
It's a much better experience and result than reading on a screen, editing it while you're reading, getting distracted, jumping back and forth between doing other things.
https://www.youtube.com/watch?v=vtIzMaLkCaM
As is George Gopen who also has a wonderful book that is more into the finer points of where to stick which part of the sentence. Williams and also McEnerney's lecture are much more motivating.
To some it will be too obvious. But English speakers (especially English as a second language people) outside the US have often never heard of it.
Just the audio version is sufficient, especially if you can listen to it on a daily commute. They give specific advice on how to simplify sentences that have multiple dependent clauses into a more compact form, which can be particularly useful for technical writing.
https://www.chronicle.com/article/50-years-of-stupid-grammar...
"The Elements of Style does not deserve the enormous esteem in which it is held by American college graduates. Its advice ranges from limp platitudes to inconsistent nonsense. Its enormous influence has not improved American students’ grasp of English grammar; it has significantly degraded it."
Probably a more brutal takedown than deserved but I'm not at all sure it's wrong.
It's a great book to use for guidelines to start with when building out your own style. If youre an editor and want to use it to compell others to write with a style, it's less useful.
The absolute, invariable first rule in tech writing is to know your audience.
Understand not just their technical problems but take the time to empathize with why they have these problems in the first place.
Tech writing isn't about documenting, it's about finding the best way to explain something to people so they can solve their problems.
Oh, and use an editor (the human kind, not the digital kind.)
This is so important (IMNSHO). It's fairly obvious, that editors are becoming a "lost art."
My mother was a scientific editor, and she was brutal (she edited some of my work).
It's really hard to find fiction books, that are less than 500 pages.
I read a story about Stephen King. Apparently, he hates being edited (most writers don't like it).
When he was just starting out, he was forced into being edited. I remember reading 'Salem's Lot, back in the 1970s. It was an awesome book (Relatively short, succinct, scary as hell), and made me suddenly become a Stephen King fan.
As he got more and more famous, he started being able to bully his editors, to the point where his work is barely edited at all.
And it shows.
I really can't read him, anymore.
Historical novels are often big offenders. Like the author has done a ton of research, not a bad thing, but can't bear to leave any of it out, and there is no editor to say that's too much, people don't need to know how big the potato patch at the Palace of Versailles was.
Having read the "Great Illustrated Classics" edition of Moby Dick as a kid, and watched the Gregory Peck film, I can confidently assert I NEVER want to read the whole thing.
Even those "condensed" versions had enormous swaths of nothing in them!
I've grown to love it. It was a long road. Once you start disciplined writing an editor becomes like a personal trainer who helps you be your best. Until I learned to write with more steel and less fire, ego ruled my writing. The familiar sins are;
- loving the sound of your own (inner) voice
- showing off what you know rather than considering what the reader might care to hear (and muddying waters so as to appear deep)
- pretentious talk (circumlocutory linguistic gymnastics)
A good editor gets to know your weaknesses and corrects them gently.
Or maybe not-so-"gently" .. I'll take useful constructive criticism (regardless of harshness) over unactionable "reword" every dang day of the week (and 3 times on Sunday)
To play editor for a moment — your sentence needs no comma, and it’s easy to find fiction books with fewer than 500 pages ;)
Was a clause omitted?
I look for books in a certain genre, though.
I find myself retreating to classics that are over 30 years old, because the new stuff is so unreadable.
I'll probably start The Black Company (for like, the twentieth time), soon.
The suggestion is to never separate a subject from a verb or a verb from its object
I decided to develop the habit of the "Oxford Comma," but I don't think I have it down, yet. It also seems to be "un-American." American English does not like commas.
But be consistent!
If you always use the Oxford comma, you never have any confusion.
When you sometimes use it and sometimes don't, confusion proliferates
For SF & F this seems to be a deliberate choice, from what I understand. This is from an iterview with Ted Chiang:
TC: I think the reaction varies, because science fiction is a more commercial genre. There are a lot more people in science fiction whose goal is to make a living from writing fiction by publishing one or more novels a year. And people who enter science fiction generally receive more messaging about fiction writing as a sole source of income than, say, people entering mainstream fiction. The messaging there is different: get an MFA, teach; it’s understood that your teaching position supports your career as a writer. For writers entering science fiction, that’s not really a thing yet. We’re maybe getting there, but the messaging they receive is mostly: Be very prolific.
https://culture.org/an-interview-with-ted-chiang/
>> As [Stephen King] got more and more famous, he started being able to bully his editors, to the point where his work is barely edited at all.
Yeah, I kinda noticed that too. I picked up a book of his and couldn't finish it because it felt like every episode in the story was written so that it took maybe ten, maybe fifty more pages than it really needed to. Extreme padding.
I think Liu Cixin also went through something similar. The Dark Forest was lean and mean. The next two books were progressively fatter and more verbose and full of aimless meandering. Though maybe that was an attempt to complete a trilogy to capitalise on the first book, if I'm more cynical.
First drafts tend to be verbose. Poor editing contributes to that kind of prose slipping through into publication.
As to huge page counts, mysteries are similar to science fiction as genres but I don't see a push to expand to huge sizes.
All genres are places where earning a living is possible. Someone said if you have a popular mystery series, every public library will buy at least one hardback copy of each of your books.
If you are big time popular, they might order 20 copies, like the last few Sue Grafton books.
Similar for ebook and audio books.
Allow me to introduce you to the myriad Maigret novels by George Simenon. :) They are my favorite filler books when I want something good at only 150-200 pages.
I will mention that I highly recommend Simenon's writing, Maigret series and others. He's a fine writer. The TV series with Michael Jambon is excellent. The Maigret stories are the right length to turn into an hour show without losing too much of the interesting details.
Someone writing new mysteries today probably could not get a single book that short accepted by a publisher.
Examples include Robert Heinlein in Science Fiction, James Michener in general fiction, Herman Wouk in general fiction. For Wouk, his well known Caine Mutiny is a fairly long book, but it's tightly written. Later works not so much.
Compare "Foundation" with "Foundation and Earth" or "Foundation's Edge". Or "The Philosopher's Stone" with "The Order of the Phoenix". The former were well-edited and succinct. The latter were overly long, in some cases sorely repetitive with large amounts of padding, and a good editor could have cut them down by at least half without losing much.
And let's not even get into Robert Jordan...
Even the best authors need an editor.
I've worked as a reviewer/editor (with "compensation" in the form of the acknowledgment page) on a handful of technical books
Overall, of the ~7 authors I've reviewed/edited, I can confidently assert only one was wrong, but ALL wrote in nearly-unfollowable ways
I'd say the opposite
As someone who's recently been put back under the "cosh of an academic style guide", I can definitely say the "academic style guide" does NOTHING to help with editing ... it's all about FORMAT
Format is nice, and all ... but almost 100% irrelevant to the content
If major publications can't employ decent editors what hope have you?
https://web.archive.org/web/20170816111301/http://serenity-s...
https://web.archive.org/web/20170619192710/http://www.sereni...
Too bad Serenity Software appears AWOL.
The more effectively you can imagine perspectives other than your own, the more easily you can come up with creative solutions, communicate well, and overall just be a more pleasant person to be around.
While that’s definitely true for tech writing generally, I feel it’s usually not the best advice for someone wanting to improve their technical writing.
Tech writing is first and for all “writing”. I feel that’s where a lot of people are struggling already: they may know vocabulary and grammar, but they have difficulties to write a well structured text. Even a single paragraph consisting of two or three sentences can be very hard for many people to actually think about. They may have been focusing on “shortcut” rules such as “maximum X words per sentence” or “maximum Y sentences per paragraph”. But those are more often than not a distraction to actually think about a logically structured text.
It’s important to have a narrative to guide the reader through the text, presenting new pieces of information in a logical sequence, and anticipating how a reader could misunderstand what you’re trying to say. For fiction writers, coming up with a narrative feels natural (even if it still can be hard). However, non-fiction writers may not even realise that they need some kind of narrative.
You do need to know your audience to anticipate how your reader could misunderstand your text, but I think it’s best to start practising by writing for yourself or someone like yourself. Write something about a topic you know pretty well, but do not master perfectly. Then, read what you’ve written one or two weeks later, and see if it still makes sense to you. If some parts seem confusing, try improving them.
You could do the same with texts written by someone else: whenever you think the text is confusing or unclear, try improving itself.
Do not just quickly add a word or sentence that specifically addresses your confusion, but take a step back and try to understand what caused the confusion. Try to really think about the order in which information is presented, whether that information is explained clearly, and whether all information in your text is necessary to understand the point you’re making.
When writing about a concept, or a system, do something like
---
This system consists of
- A
- B
- C, (but see notes on C below)
(and then do the same for C further down)
---
Label each section with a header and have a ToC that has every header in it.
All this will let you do two things:
- cut down on bullshit, and be concise and precise.
- see and quickly change the structure of your document
Be prepared for several rounds of fine-grained heavy editing process. FWIW, I benefited greatly from my interaction with the LWN editors by contributing a handful of articles. Here's a somewhat recent example[2].
[1] https://lwn.net/op/AuthorGuide.lwn
[2] "A QEMU case study in grappling with software complexity" — https://lwn.net/Articles/872321/
Article-length (i.e. ~ 1K word) pieces for a publication where editors will actually take time and care to work with you--which is by no means a given these days is definitely the path I would recommend. Note that this is different in a number of ways from technical documentation. At the same time, it's also closer than something more literary or (for the most part) something more like reporting which has its own style (and other rules).
While my professional writing has been mostly academic, I find the progression is similar to tech writing.
First you learn to show your erudition and command of the ingroup speech.
Then, if you have a genuine desire to communicate, you progress to simpler yet precise language, stop using the big words when not necessary (often, they are just signaling and gatekeeping) and develop empathy for and understanding of the audience.
1: https://cdn.static-economist.com/sites/default/files/store/S...
clearly mark twain took the orwell advice to heart.
Anyone looking for a good system of producing documentation should check out:
https://documentation.divio.com/
Which has a 30-min presentation:
https://m.youtube.com/watch?v=t4vKPhjcMZg
Prior HN posts on the system are here:
https://hn.algolia.com/?q=https%3A%2F%2Fdocumentation.divio....
https://www.heinrichhartmann.com/posts/writing/
I now regard it as a minimum bar that I can explain the broad outlines in plain language.
Anyone who can’t is is a fucking fraud.
Improving open source project READMEs and documentation is another great way to practice writing.
I am writing an O'Reilly book now and having a professional editor will help you learn the common errors you're making.
You should try to write short paragraphs, short sentences, and at a 4th-6th grade reading level. Good writing for literature is a lot different that good technical writing.
A good novelist may write at a 12th grade reading level, may use complicated words, and will use literary devices like allegory and foreshadowing.
A good technical writer should explain a concept in the most simple way possible. They should explicitly avoid literary devices like foreshadowing - their goal is to explain the concept in a straightforward manner. They should also avoid big words and long sentences. A large portion of technical readers are not native English speakers, so only the most basic words should be used.
In many cases, people want the tl;dr only, so I try to give them that first.
How do you come up with "at least 5 minutes for a blog post"
A blog post should be as long as it needs to be - and no longer
In technical writing, clarity reigns. Clarity above all else. Lists? Use bullet points. Topics? Make headings. Do two terms seem similar? Change your wording to make the differences obvious. Is there a technical term? Use it consistently. Are you using the same word in different senses? Use two different words. Using negatives? Use positives instead, they are easier to parse.
If you are good at the details of writing, your thoughts and ideas become clearer, because clear writing exposes the flaws in your ideas.
Recommended book: Style: Lessons in Clarity and Grace.
I also recommend finding a topic to blog about. You don't need to be an expert. Just keeping an active blog teaches you a lot about writing.
Pick a product/ technology you’re familiar with and which has great documentation.
Go to their docs, and pick a page that is on a topic you know well.
Read only the title of the page.
Write the documentation.
When you’re done, compare your results with theirs. What headings did you choose vs theirs? Why do you think they chose the ones they did? How does your document flow vs theirs? How’d they illustrate the concepts vs you?
It’s an informative and fun exercise, at least to me.