Ask HN: How to level up your technical writing?
161 comments
Tech writer here.
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.)
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.)
> 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.
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.
> It's really hard to find fiction books, that are less than 500 pages.
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.
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.
While I see where you’re coming from re: The Three Body Problem Vs the rest of the series, the core ideas in the Dark Forest and Deaths End are so exciting that I can’t help but feel the rest of the story is a justification for exploring them.
Oops- I meant The Three Body Problem was lean and mean Thanks!
> extreme padding
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.
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.
I think page padding is more a thing in self publishing. I'm part of a few fiction writer communities and longer (in general) makes more money. You are advised to start with short stories and graduate to novels as soon as possible. This is especially true for authors enrolling their books in Kindle Unlimited. They are paid per page read. The more pages they can have the reader go through without boring them enough to just quit, the more they get paid.
> Apparently, he hates being edited (most writers don't like it).
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.
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.
[deleted]
>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)
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)
You can see exactly the same with other authors. Asimov and J. K. Rowling, to pick two obvious candidates.
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.
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.
>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'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
> It's really hard to find fiction books, that are less than 500 pages.
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?
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?
https://www.btb.termiumplus.gc.ca/tpv2guides/guides/pep/inde...
The suggestion is to never separate a subject from a verb or a verb from its object
The suggestion is to never separate a subject from a verb or a verb from its object
Wow, that's a great link. Thanks for posting that. I'd never seen it before as a reference.
Hey, thanks for that! Proper comma (and semicolon) usage is always a challenge for me.
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.
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.
I don't especially care whether you choose the Oxford comma, or not.
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
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
On the other hand American English LOVES periods, leading to visual abominations like N.A.T.O.
Fair point.
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.
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.
In the great short books category, Willa Cather’s plains trilogy books are like 150-200 pages each, they’re fast reads and the prose is excellent — I’d start with ‘O Pioneers!’
That's not just him, it seems to happen to a lot of authors when they get famous. They get more clout and can push back on the editors, or the editors become afraid to cut too much, and suddenly you have bricks where half the words could be removed.
You can see it in action by looking at a boxed Harry Potter set.
I always like to point at Victor Hugo. In Les Misérables, apparently (I didn't count), more than a quarter of the text is essays which do not move the plot forward. The essay about Waterloo is the most egregious example.
Apparently that was a bit of the style at the time (one of them delves into the Paris sewer system) to kind of "show off". Some other contemporary works are clearly written to be serialized.
Once downloaded a copy of Hound of the Baskervilles, broken into chapters as separate files. Each chapter was almost exactly the same length, within a few hundred characters, showing that it had been serialized first and chapters were sized for publication.
I'm trying to remember if it was Dumas, but some French author was reputedly paid by the word, so all their dialogue is incredibly drawn out ("I have a question." "What is the question?" "It is, as you might expect from me, a simple question." "By all means, please, present me with the question, that I may resolve your puzzlement." ... etc.).
That's one of the ongoing theories as to why Moby Dick was so long ... not merely to accentuate the 99.99% bordedom of whaling (with the 0.01% of "excitement"), but because he'd get paid better if it were longer
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!
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!
When I read Moby Dick I found it a quick read for the length. Full of incidents and plot.
Many modern novels seem that way too. Not the elaborate dialog, but endless rambling descriptions.
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.
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.
while not a big Western fan, I do find Louis L'Amour's compact descriptive format to be intensely engaging
> It's really hard to find fiction books, that are less than 500 pages.
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.
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.
These days shorter fiction is almost always published as part of a collection, unless you are selling on line or self publishing in print.
Is this in response to the wrong comment? I'm giving an example of the opposite of what you're saying.
What I meant was that books like the Maigret novels probably wouldn't be published as free standing books, but packed into collections, say three or four of them together, to get closer to the magic 500 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.
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.
You can literally buy these as paperback though, directly from the publisher: https://www.penguinrandomhouse.com/series/IMA/inspector-maig....
Of course, but remember that they were first published in 1931. The last ones were 1973 but by then they were so popular they could go against the already established trend of longer books.
Someone writing new mysteries today probably could not get a single book that short accepted by a publisher.
Someone writing new mysteries today probably could not get a single book that short accepted by a publisher.
If you follow the publication of big name writers, there is a tendency for their later works to get longer and longer, and, as you say, harder to read.
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.
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.
I can only read his short fiction with few exceptions. He got to the point where he would take 50 pages (exaggeration, but still...) to describe, I dunno, a room. Okay, so the room is important, but is it that important?
I've never read King, but do recall the hilarity of Goldman's "The Princess Bride: S. Morgenstern's Classic Tale of True Love and High Adventure, The "Good Parts" Version" ""editorial' comments throughout ... like "with this and that, we move to chapter 4"
Eh, depends...as you point out it is becoming a "lost art".
The average quality of editors is utterly abysmal, so if you're pretty handy with style, or have lived under the cosh of an academic style guide for long enough you can probably get by without an editor.
>lived under the cosh of an academic style guide for long enough you can probably get by without an editor.
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
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
Then it's a lost cause, you can't expect an editor to understand content, their function is to impose style, any reasonable exposure to formal language should be sufficient (but actually I disagree completely).
If major publications can't employ decent editors what hope have you?
If major publications can't employ decent editors what hope have you?
I think many people write off empathy as being about warm and fuzzy feelings, and don't realize that it's a very useful skill that can be improved with practice.
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.
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.
> The absolute, invariable first rule in tech writing is to know your audience.
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.
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.
Grammarly is still better than no editor.
IMO not by much. I mean, it catches out and out errors which is something I guess. And it gives some generally applicable feedback about excessive use of passive voice, overly long sentences, etc. But for the most part it doesn't really improve your writing in terms of structure, clarity, etc.
I still use Grammarly in my browser, but had to turn it off on my phone and elsewhere ... it's a great idea of a tool ... but ends up being unworkable too often :(
Not really:
https://web.archive.org/web/20170816111301/http://serenity-s...
https://web.archive.org/web/20170619192710/http://www.sereni...
Too bad Serenity Software appears AWOL.
https://web.archive.org/web/20170816111301/http://serenity-s...
https://web.archive.org/web/20170619192710/http://www.sereni...
Too bad Serenity Software appears AWOL.
Lots of great advice here. One piece of advice I got from my publisher when authoring a technical book was to first break down what I was going write into headings and subheadings, and if possible, into sub-subheadings. Then review that to see if your flow is coherent and whether there are sections that are missing, or could be extracted into another text.
Personally, my process after this is to express my thoughts in bullet points, followed by inserting any placeholders and captions for any graphics (e.g. charts or diagrams), and then finally I start rewriting my bullet points into proper sentences, expanding my examples, and adding any interstitial text necessary to make things flow.
Also, I see some comments on keeping things short and to the point. In general, I agree with this, but depending on the medium, sometimes it doesn’t hurt to inject a bit of personality into your writing. Technical writing can be dry at times, and this can deter engagement. Try to use concrete examples whenever possible or refer to other supporting texts.
Personally, my process after this is to express my thoughts in bullet points, followed by inserting any placeholders and captions for any graphics (e.g. charts or diagrams), and then finally I start rewriting my bullet points into proper sentences, expanding my examples, and adding any interstitial text necessary to make things flow.
Also, I see some comments on keeping things short and to the point. In general, I agree with this, but depending on the medium, sometimes it doesn’t hurt to inject a bit of personality into your writing. Technical writing can be dry at times, and this can deter engagement. Try to use concrete examples whenever possible or refer to other supporting texts.
Wanted to add that relying on an editor is absolutely key. It doesn’t necessarily have to be a professional, a friend or colleague with strong communication skills will do. Edit your own work mercilessly as well, but only after you’ve put your main thoughts down. After a night of intense drafting, put your text in a drawer and come back to it in a day or two.
> Also, I see some comments on keeping things short and to the point
I think this is true. Another way of saying it might be to write things intentionally and make sure each sentence contributes to a goal. You can have humor and personality in the paper, but make sure you don't have filler or meaningless words that you're just writing off as personality.
I love when a document is easy to read and is thorough.
Side rant: I hate when people use an acronym in a document and never state what the acronym stands for. Take the extra 10 seconds and type it out the first time you use it with the acronym version in parentheses directly after.
I think this is true. Another way of saying it might be to write things intentionally and make sure each sentence contributes to a goal. You can have humor and personality in the paper, but make sure you don't have filler or meaningless words that you're just writing off as personality.
I love when a document is easy to read and is thorough.
Side rant: I hate when people use an acronym in a document and never state what the acronym stands for. Take the extra 10 seconds and type it out the first time you use it with the acronym version in parentheses directly after.
An acronym glossary up front is often helpful. But the current practice seems to be to add copious whitespace until it fills two or three pages, when a fraction of that would suffice.
I think you phrased it well. The distinction I wanted to make is that it's more about clarity of thought than absolute brevity.
Two things I recommend: the Google tech writing courses: https://developers.google.com/tech-writing
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/...
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/...
Have you taken the Google tech writing course? Were there any big takeaways for you?
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."
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."
15 hours ago, this book was 15 bucks, and now that I went back to the page, the book is 39 bucks with "Only 1 left in stock" message.
Products on Amazon even get the Hug of Death™.
Products on Amazon even get the Hug of Death™.
You can also read it on Open Library for free :)
https://openlibrary.org/works/OL2743029W/BUGS_in_writing?edi...
When I left high school for college (to pursue engineering) I was quite envious of my friends in the liberal arts - they were assigned papers all the time and I had no outlet for writing (something I enjoyed quite a bit).
I have realized that written/technical communication is a great differentiator.
I journal every day but specifically to your question I would say just start writing.
Knowing your audience is key. I usually include an executive summary section at the top of any design document or product requirements document for a high level view of why people should care. Then I dive into a background or history to give context. At the end of the day it's a narrative and follows similar arcs - just with more direct prose and specific facts. I'll also drop this resource here from the Pragmatic Engineer newsletter. [0]
[0]: https://newsletter.pragmaticengineer.com/p/software-engineer...
I have realized that written/technical communication is a great differentiator.
I journal every day but specifically to your question I would say just start writing.
Knowing your audience is key. I usually include an executive summary section at the top of any design document or product requirements document for a high level view of why people should care. Then I dive into a background or history to give context. At the end of the day it's a narrative and follows similar arcs - just with more direct prose and specific facts. I'll also drop this resource here from the Pragmatic Engineer newsletter. [0]
[0]: https://newsletter.pragmaticengineer.com/p/software-engineer...
Practice writing every day at all times.
Replying to an email? Do the short summary at the top, then write a paragraph or two about the reasons/details/etc - these are also great references.
Encounter an issue and solve it? Write up what it was and what fixed it on a wiki, blog post, even just an email to yourself.
Hacker news? Write comments that are detailed.
Replying to an email? Do the short summary at the top, then write a paragraph or two about the reasons/details/etc - these are also great references.
Encounter an issue and solve it? Write up what it was and what fixed it on a wiki, blog post, even just an email to yourself.
Hacker news? Write comments that are detailed.
Couldn’t agree more that narrative is the key. If you’re telling a compelling story (which can look very different for different audiences), you kind of get the rest for free, because you will have the reader’s attention.
Love your tip of how to structure a text. Thanks!
Blogging & measuring average time on page is a great way to see if you're able to write content that's relevant and engaging for readers. Average time on page should be at least 5 minutes for a blog post.
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.
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.
> Average time on page should be at least 5 minutes for a blog post
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
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
I disagree with using time on page as a metric. If you can answer the question in half the time, good for your readers.
In many cases, people want the tl;dr only, so I try to give them that first.
In many cases, people want the tl;dr only, so I try to give them that first.
Technical writing benefits from Practical Style (the reader's time is important, the reader wants to get a job done, easy parsing of sentences is important), so I'd recommend one of the two best books about writing in English:
Joseph 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.
Joseph 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.
Thanks for the literature tips, will definitely get one of the books right away. Will also learn more about Practical Style as I haven’t heard about that.
I came in to write exactly what you wrote. +1
I have a bit of an unusual suggestion. One thig that had helped me is reading "The Economist". Their style is succinct, doesn't make lot of assumptions about reader's prior knowledge. Many a times I have read articles in it about many of the areas which I am barely familiar with and come out better informed. Probably that's what one would strive for in technical documentation.
Their style guide [1] is one of my references when trying to improve my own writing.
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...
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...
Definitely one of the best-written publications out there. Not as "literary" as The New Yorker. But brings in a certain amount of cleverness/humor/storytelling that newspapers (by design) mostly lack outside of feature stories where some of those elements can be overdone.
https://imgur.com/a/rWEmPI9
clearly mark twain took the orwell advice to heart.
clearly mark twain took the orwell advice to heart.
Since you said you're willing to try "what it takes": I suggest to try contributing a couple of articles to LWN.net[1]. You'll gain valuable experience working with highly competent editors.
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/
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/
I'll also throw in a plug for opensource.com.
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).
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).
After writing a lot of text, print it out, take it outside if the weather's nice, put away your laptop, tablet, and phone, sit down with a pen, read over the entire document, and mark up the paper with your pen.
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.
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.
And on the next iteration, change the column width a little.
Write consistently and spend time rereading what you write before/after you publish. Read out loud. Any time you find a confusing or unclear sentence, rework it. Get rid of unnecessary words.
I've been doing this for 1-3 blog posts per month for the last 4 years and I think my writing is decent now.
It didn't come naturally. I hated editing all my life until I took a course in college and realized I could actually write clearly if I just spent a little time reading and reworking what I wrote.
The only directly related book I'd recommend is On Writing Well.
I'd also suggest reading clear and simple authors like Hemingway (A Movable Feast), Antoine de Saint-Exupéry (Wind, Sand and Stars), and Beryl Markham (West with the Night).
But fundamentally: consistent practice, rereading, and editing.
I've been doing this for 1-3 blog posts per month for the last 4 years and I think my writing is decent now.
It didn't come naturally. I hated editing all my life until I took a course in college and realized I could actually write clearly if I just spent a little time reading and reworking what I wrote.
The only directly related book I'd recommend is On Writing Well.
I'd also suggest reading clear and simple authors like Hemingway (A Movable Feast), Antoine de Saint-Exupéry (Wind, Sand and Stars), and Beryl Markham (West with the Night).
But fundamentally: consistent practice, rereading, and editing.
I took this idea from my PhD supervisor and found it to be incredibly useful.
Before writing down a long form doc, make a quick mondmap answering the following:
1. What are the three core ideas you’re writing about? 2. What are the three main criticisms / counter arguments against your ideas? 3. How do you plan to respond to the criticisms?
Depending on the subject matter and length of the doc, you may need more or less than three. But see if you can get this mind map written first. Then, see if you’re convinced the ideas are worthy of writing. Only then write the long form.
Before writing down a long form doc, make a quick mondmap answering the following:
1. What are the three core ideas you’re writing about? 2. What are the three main criticisms / counter arguments against your ideas? 3. How do you plan to respond to the criticisms?
Depending on the subject matter and length of the doc, you may need more or less than three. But see if you can get this mind map written first. Then, see if you’re convinced the ideas are worthy of writing. Only then write the long form.
*mindmap
My advice: read lots of old, old technical documentation. For some reason, technical writing became much worse after 1990 or so. Probably something to do with the commoditization of tech.
To be a good technical writer, you must understand who needs what and why, then figure out how to solve that the best way based on the context.
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....
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....
Your HN handle is from 2016 and has 508 karma. You could probably learn a lot by trying to explain stuff here in comments and see if it clicks with folks.
Benefits: You get prompt feedback as to the quality of your writing. You may build a reputation.
Downside: That feedback may not exactly be sugar coated.
Benefits: You get prompt feedback as to the quality of your writing. You may build a reputation.
Downside: That feedback may not exactly be sugar coated.
Really good suggestion, I have not been very active commenting here. Thanks!
A few pointers from my own experience (usually in the context of design or proposals):
- why does a document need to be written? Is it to be discussed, debated, just documentation? Let this drive what really needs to be written. Often I’ve seen design documents with lengthy sections on information that is already well agreed upon or commonly understood, just adds noise for the reader.
- consider the audience. Engineers may read a document and have specific prior context that can be omitted, whereas a product manager may get lost in too much technical detail. Tailor your document to your audience, and use the appendix for extra details if someone wants to dig in further.
- keep it brief. Focus on information required to get the necessary outcome and convey the information clearly. Starting with an outline of headers is helpful as well.
- think of good writing you’ve come across. It was likely clear and succinct enough. In my own writing I used to include every last detail to make sure the reader was the most informed about how I reached some conclusion, but then realized too much info becomes counterproductive and doesn’t focus the reader on what matters.
- why does a document need to be written? Is it to be discussed, debated, just documentation? Let this drive what really needs to be written. Often I’ve seen design documents with lengthy sections on information that is already well agreed upon or commonly understood, just adds noise for the reader.
- consider the audience. Engineers may read a document and have specific prior context that can be omitted, whereas a product manager may get lost in too much technical detail. Tailor your document to your audience, and use the appendix for extra details if someone wants to dig in further.
- keep it brief. Focus on information required to get the necessary outcome and convey the information clearly. Starting with an outline of headers is helpful as well.
- think of good writing you’ve come across. It was likely clear and succinct enough. In my own writing I used to include every last detail to make sure the reader was the most informed about how I reached some conclusion, but then realized too much info becomes counterproductive and doesn’t focus the reader on what matters.
>consider the audience.
And I'd add to that: Be reasonably consistent. Don't be belaboring what a microprocessor is and what it does in one sentence. And then throwing around jargon like registers, branch prediction, and hyperhtreading in the next without any explanation.
One thing I miss writing for the web is that footnotes don't work very well. When I was writing research notes, I really liked footnotes for--among other things--providing some parenthetical detail about technical terms and the like in a way that didn't break up the flow. Unfortunately, on the web, footnotes generally break up the flow more than just adding the detail inline.
And I'd add to that: Be reasonably consistent. Don't be belaboring what a microprocessor is and what it does in one sentence. And then throwing around jargon like registers, branch prediction, and hyperhtreading in the next without any explanation.
One thing I miss writing for the web is that footnotes don't work very well. When I was writing research notes, I really liked footnotes for--among other things--providing some parenthetical detail about technical terms and the like in a way that didn't break up the flow. Unfortunately, on the web, footnotes generally break up the flow more than just adding the detail inline.
For more of a process on how to get docs cycle through a dev review - The oxide computer RFD process - https://oxide.computer/blog/rfd-1-requests-for-discussion. I tried to use something similar for my team but got a lot of eye rolls that docs would need source control. We use a wiki but it's messy and not a lot of review control. Writing the doc is one thing. Making sure it's effectively communicated, reviewed, versioned and published should also be a part of the documentation process.
One pesky little detail is that documents take a lot of thought to write and this translates into a good bit of time to get a document out for review. If you have a "how fast are you closing your JIRA tickets" manager, it can be hard to justify and will come back to bite you (unfairly so, but such is the life of a sw. engineer).
One pesky little detail is that documents take a lot of thought to write and this translates into a good bit of time to get a document out for review. If you have a "how fast are you closing your JIRA tickets" manager, it can be hard to justify and will come back to bite you (unfairly so, but such is the life of a sw. engineer).
Check out this past discussion thread (post link as well as comments): https://news.ycombinator.com/item?id=20061078
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
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
I've developed my skills by writing documentation, presentations, blog posts, in-depth articles, and Stack Overflow answers. I always start out by thinking about who my audience is and why they're reading what I wrote, and I always finish by trying to cut down the material I've written so it doesn't contain anything unnecessary.
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.
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.
Find good examples of well written documentation and emulate those.
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.)
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.)
Some are suggesting more reading, and others are suggesting more writing. I propose that it is best to do both, and maintain active feedback loops between the two.
Good suggestion! Do you have any technical docs that stand out as extra good in your opinion?
I remember the Ansible docs as pretty good.
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.
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.
Stripe is very often mentioned as an example of great docs - https://stripe.com/docs
Thanks! Will definitely check that out. I know I have stumbled in there before, but not having used the service I have not really looked around too much.
K&R, or anything else Brian Kernighan.
I had to look up what K&R was but makes sense after some searching. That book is probably worthwhile for lots of other reasons, even if I program in Go for most tasks. Thanks for the pointer!
In general, I like to do something like this:
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.
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.
Really cool tip!
The best way in my opinion is to write, and write more. Once you write your first doc, send it to someone who you believe may be your target audience and have them critique it. What’s confusing to them? What’s not?
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.
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.
This! The best way to get better at writing is to write :)
Lots of good advice already (except there are better sources for writing style advice than Strunk & White). Here's one I and my linguist wife like:
Write on paper first.
Paper is more immediate and has fewer distractions, fewer ways to go back and edit at once, and leaves a bit more time to think. It doesn't require looking at a screen, which you probably do enough of already.
Sure, typing it up is an extra step, but it can be a good editing step. Having edited (to the best of my ability) some of my wife's writings, I have been able to correctly guess when she wrote directly into the computer simply by the writing being less coherent.
Write on paper first.
Paper is more immediate and has fewer distractions, fewer ways to go back and edit at once, and leaves a bit more time to think. It doesn't require looking at a screen, which you probably do enough of already.
Sure, typing it up is an extra step, but it can be a good editing step. Having edited (to the best of my ability) some of my wife's writings, I have been able to correctly guess when she wrote directly into the computer simply by the writing being less coherent.
Very true that we sit by our screens way too much. Any reasonable work away from it is probably for the best.
On this note I would like to share a really good tip (but slightly out of topic) that I got in the comments on some HN post some time ago; don’t use your phone or Internet until late morning, or at least after having really dug in to work for the day. This really helps to focus on the work at hand and avoid distractions.
Getting into "work mode" really helps. I did a similar thing during my Ph.D. studies - no reading email or news or gaming until lunch time, only work. After lunch, all options were open, but I then had work so swapped in that I kept on working.
Here's a (imho) pretty neat post on technical writing that was recently linked on HN:
https://www.heinrichhartmann.com/posts/writing/
https://www.heinrichhartmann.com/posts/writing/
Someone else mentioned Strunk and White's Elements of Style, but in the true spirit of that book let me just cut to the chase and say, "omit needless words."
Our brains only have so much space in them so you only get to cram a small number of words into someone else's brain; make them the most productive words possible.
When writing, it's harder to remove words than write them.
Our brains only have so much space in them so you only get to cram a small number of words into someone else's brain; make them the most productive words possible.
When writing, it's harder to remove words than write them.
A bit like code then, optimize for easy reading rather smarts when writing it.
Start with lists.
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
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
I found the Hemingway style of getting to the point in simple English is the best way to get my point across. There are several apps that will help you write like Hemingway.
Get to the point. Usually in the first two paragraphs. The entire meat of a memo or chapter is on one page. The rest of the memo or chapter is supporting material with examples, clarifications, diagrams, and context showing how this idea relates to a different idea.
In meetings, I usually present only the first page or one diagram that summarizes the entire memo. I usually tell people to read the whole thing if they want more details.
I am also in the habit of sharing my drafts with a lot of people so they know what I am up to. By the time it’s completed the audience has probably already seen it twice . This helps with buy-in. As I have already met with people who have concerns or objections.
Get to the point. Usually in the first two paragraphs. The entire meat of a memo or chapter is on one page. The rest of the memo or chapter is supporting material with examples, clarifications, diagrams, and context showing how this idea relates to a different idea.
In meetings, I usually present only the first page or one diagram that summarizes the entire memo. I usually tell people to read the whole thing if they want more details.
I am also in the habit of sharing my drafts with a lot of people so they know what I am up to. By the time it’s completed the audience has probably already seen it twice . This helps with buy-in. As I have already met with people who have concerns or objections.
Strunk and White.
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.
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.
I'll also add the course from The Great Courses - 'Building Great Sentences: Exploring the Writer's Craft' by Brooks Landon.
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.
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.
Unfortunately, this is now apparently behind a sign-up wall but for a counterpoint:
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.
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.
The article is needlessly contrarian and negative. The book is useful to get students or anyone playing a trade writing from 3/10 to a 7/10. A lot of critics lose sight of this.
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.
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.
That criticism would hold more water if it were more well written.
I have failed deeply and fundamentally as a technologist by not being able to explain the technology in plain language.
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.
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.
While I see where you're coming from, get deep enough into specialized concepts and a "plain language" explanation that assumes no prior knowledge is going to have to hand wave away a huge amount of detail and may not even be completely accurate in many respects. Yes, you can probably give an intelligent person the gist of what's going on, perhaps by analogy, but it may not really be an "explanation."
Write a new technical article each week on your blog. Get feedback (by sharing them). You'll improve over time.
3 recommendations:
1. Write more.
2. Write clearly.
3. Know your audience.
One thing: do it a lot. Set a time every day and practice. Some prompts to get you started:
1. Write a white paper on the application of a piece of OSS that you like.
2. Write a usage description for one of your one-off projects/scripts.
3. Write a technical paper about an algorithm you used in a specific instance.
4. Explain the solutions to classic interview problems (eg binary tree reversal) in written form.
5. At work, write up brief pitches for new product improvements you have.
In all cases, consider the audience and what needs to come across to accomplish your goal.
1. Write a white paper on the application of a piece of OSS that you like.
2. Write a usage description for one of your one-off projects/scripts.
3. Write a technical paper about an algorithm you used in a specific instance.
4. Explain the solutions to classic interview problems (eg binary tree reversal) in written form.
5. At work, write up brief pitches for new product improvements you have.
In all cases, consider the audience and what needs to come across to accomplish your goal.
Lots of solid advice already.
If you are up for it, you could try moonlighting as a writer for technical content marketing agencies. You get paid on the side, while also subjecting your writing to editorial criticism until it is ready for publication.
https://draft.dev/write
https://contentlab.io/writeforus/
If you are up for it, you could try moonlighting as a writer for technical content marketing agencies. You get paid on the side, while also subjecting your writing to editorial criticism until it is ready for publication.
https://draft.dev/write
https://contentlab.io/writeforus/
Start writing short stories and essays about literally whatever is on your mind that day.
Every type of writing you practice makes you better at every other kind of writing. The part of your brain that learns to make fiction flow will do the exact same thing for complex technical documents.
Also, find someone you think is amazing at technical writing and ask them to sit down with you and revise something you wrote. Study what they want to change and why.
Every type of writing you practice makes you better at every other kind of writing. The part of your brain that learns to make fiction flow will do the exact same thing for complex technical documents.
Also, find someone you think is amazing at technical writing and ask them to sit down with you and revise something you wrote. Study what they want to change and why.
It's not strictly from the technical writing corner, but I've learned a lot from the book "The Craft of Scientific Writing" by Micheal Allay. It's more geared towards scientific papers, but I've found the style papers are structured to be a very useful starting point for design documents and runbooks. I tend to start with something like that, and adjust it according to the audience.
The book is available for download - http://quantum.phys.unm.edu/400-18/AlleyTheCraft.pdf
Google has some classes on this, developed by their Tech Writers:
https://developers.google.com/tech-writing
Originally, the material was targeted at SWEs, trying to give them pragmatic ways of thinking about the advice you'll read elsewhere in this thread. I haven't kept up with it, so I don't know if that's still the focus.
https://developers.google.com/tech-writing
Originally, the material was targeted at SWEs, trying to give them pragmatic ways of thinking about the advice you'll read elsewhere in this thread. I haven't kept up with it, so I don't know if that's still the focus.
We are running a course for exactly this! [0] Technically applications closed already but we will likely have some more space, or we will run another cohort soon so feel free to email me and I will try fit you in.
I also keep a repository of my favourite books and some other resources here [1]
And some very short advice we give to our writers here [2]
[0] https://styleguide.ritza.co/writing-course/
[1] https://github.com/sixhobbits/technical-writing
[2] https://styleguide.ritza.co/improving-your-writing/how-do-I-...
I also keep a repository of my favourite books and some other resources here [1]
And some very short advice we give to our writers here [2]
[0] https://styleguide.ritza.co/writing-course/
[1] https://github.com/sixhobbits/technical-writing
[2] https://styleguide.ritza.co/improving-your-writing/how-do-I-...
I have a whole Twitter thread on that, here:
https://twitter.com/no_identd/status/1220913617408864257
Prompted by my discovery of this book:
https://link.springer.com/book/10.1007/978-3-030-10756-7 "A Math-Based Writing System for Engineers: Sentence Algebra & Document Algorithms", by Brad Henderson
Edit:
Altmetrics just revealed to me that apparently a cheesy corporate marketing video for it exists:
https://youtu.be/X9vQoadsQ1I
Amazing.
https://twitter.com/no_identd/status/1220913617408864257
Prompted by my discovery of this book:
https://link.springer.com/book/10.1007/978-3-030-10756-7 "A Math-Based Writing System for Engineers: Sentence Algebra & Document Algorithms", by Brad Henderson
Edit:
Altmetrics just revealed to me that apparently a cheesy corporate marketing video for it exists:
https://youtu.be/X9vQoadsQ1I
Amazing.
Haven't read it, but my reaction to the 2 minute video is "excrement" [1].
[1] https://www.youtube.com/watch?v=LjHORRHXtyI
[1] https://www.youtube.com/watch?v=LjHORRHXtyI
Well, yes, but tell that to the proof assistants, automated theorem provers, academic snowclone^W^H phrasal template banks, and highly bullet pointed lists of Corporate ISO9000 series GRC Policy & Procedure Work Instruction Drafting Style Guide Manual Template Files as well as the resulting legislative outputs( via lobbying, lol). Cf. my points in the Twitter thread, on proforms, thematic relations, and one anaphora¹.
There exist only so many ways in which to formally answer arbitrary instances of the 7 fundamental questions (yes, 7, not 5—or six, like IBM's Zachman framework would have one believe.).
¹ the Dalai Lama walks into a pizza place and asks: Can you make me one with everything?
There exist only so many ways in which to formally answer arbitrary instances of the 7 fundamental questions (yes, 7, not 5—or six, like IBM's Zachman framework would have one believe.).
¹ the Dalai Lama walks into a pizza place and asks: Can you make me one with everything?
I'm from a hybrid humanities and technical background. Good writing is good writing: clear, simple, and easy to read.
Books that influenced me:
Style, by F.L. Lucas
Simple and Direct, by Jacques Barzun
For technical writing, I recommend four additional disciplines:
1.) Keep the documentation up to date.
2.) Allow and encourage your readers to give you feedback about what's unclear. Then make revisions based on this. Also, re-read what you wrote periodically, and make revisions whereever you think you can improve clarity and usefulness.
3.) Provide copious examples where you show how to accomplish useful things.
4.) Use the tool you're documenting. Find errors, corner cases, and things to be aware of and document them as comprehensively as possible.
Books that influenced me:
Style, by F.L. Lucas
Simple and Direct, by Jacques Barzun
For technical writing, I recommend four additional disciplines:
1.) Keep the documentation up to date.
2.) Allow and encourage your readers to give you feedback about what's unclear. Then make revisions based on this. Also, re-read what you wrote periodically, and make revisions whereever you think you can improve clarity and usefulness.
3.) Provide copious examples where you show how to accomplish useful things.
4.) Use the tool you're documenting. Find errors, corner cases, and things to be aware of and document them as comprehensively as possible.
I second the "Simple and Direct" recommendation. I stumbled upon it in a book store over a decade ago and I've never seen anyone recommend it before. Years after reading it, I still hear the author's recommendations in my head when writing.
[deleted]
Two recommendations:
* On Writing Well
* Google's free, self-guided technical writing courses
Using these, you should get much better at refining your writing. Write naturally, then go back and edit when rereading according to the your new skills.
Another thing to get better at is layering your message. Assume that some percentage of people drop off each paragraph. Important details for the entire audience should be front and center. Then gradually get more specific.
Boz has a nice write up on this: https://boz.com/articles/communication-is-the-job
* On Writing Well
* Google's free, self-guided technical writing courses
Using these, you should get much better at refining your writing. Write naturally, then go back and edit when rereading according to the your new skills.
Another thing to get better at is layering your message. Assume that some percentage of people drop off each paragraph. Important details for the entire audience should be front and center. Then gradually get more specific.
Boz has a nice write up on this: https://boz.com/articles/communication-is-the-job
As a first step, try and pay attention to things that annoy or frustrate you about other technical writing, and don't do those things.
I also try to assume my audience is a moron. Not because they are, but because any time you're doing technical writing, you presumably know more than them. Force yourself to not assume things are obvious just because you're familiar with them. IMO it's better for technical writing to be a tiny bit patronizing than to be lacking in vital detail. One specific example here is to either define any acronym before using it, include a glossary, or both.
I also try to assume my audience is a moron. Not because they are, but because any time you're doing technical writing, you presumably know more than them. Force yourself to not assume things are obvious just because you're familiar with them. IMO it's better for technical writing to be a tiny bit patronizing than to be lacking in vital detail. One specific example here is to either define any acronym before using it, include a glossary, or both.
This may be helpful: https://writing.stackexchange.com/a/33505/1317
>Communication is like selling - it's all about return on investment. And ROI is all based on understanding abstractions (and how they leak). You need to give the reader/listener enough of a promise they're going to get value at least proportional to the time spent consuming what you're trying to convey that they want to stick around.
>Communication is like selling - it's all about return on investment. And ROI is all based on understanding abstractions (and how they leak). You need to give the reader/listener enough of a promise they're going to get value at least proportional to the time spent consuming what you're trying to convey that they want to stick around.
I strongly commend "The Technique of Clear Writing" by Robert Gunning. I don't think it's in print anymore, but copies are still inexpensively available through Amazon and elsewhere.
Lot's of examples mention techniques, I'll mention tools. Find an editor you like to write in, extend it with plugins that help your flow if it's the kind of app that allows it, and learn all the in's and out's to make writing as easy as possible.
I don't have a strong background in technical writing, but often get compliments on my documentation and the secret is org-mode; it makes writing structured documents easy, and there are many tool for converting org-mode docs to any format needed, so it adapts to any audience.
I don't have a strong background in technical writing, but often get compliments on my documentation and the secret is org-mode; it makes writing structured documents easy, and there are many tool for converting org-mode docs to any format needed, so it adapts to any audience.
Larry McEnerney’s lecture The Craft of Writing Effectively:
https://www.youtube.com/watch?v=vtIzMaLkCaM
https://www.youtube.com/watch?v=vtIzMaLkCaM
McEnerney’s lectures are great, let me just add that he is from the very same "school of writing" (actually, the same faculty) as my recommendation, Joseph M. Williams.
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.
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.
One weakness people "on the spectrum" have is "theory of mind", which is the ability to understand that other people have different experiences, different knowledge, and even different opinions.
In writing, this manifests as not attempting to bring the reader up to speed with underlying concepts. Since they are "known". This can result in texts that only work as a reminder for those who already know the field.
I don't have a great way to "fix" that problem, but the first step is to at least be aware of it!
In writing, this manifests as not attempting to bring the reader up to speed with underlying concepts. Since they are "known". This can result in texts that only work as a reminder for those who already know the field.
I don't have a great way to "fix" that problem, but the first step is to at least be aware of it!
To more impactful convey they information, keep not only the audience in mind, but also how their brains will process that information. Then tailor content to make it easy for the receiving entity (brain) to process the information and store it effectively.
I found this guide helpful: https://www.knowledgeowl.com/home/three-tips-psychology-docu...
I found this guide helpful: https://www.knowledgeowl.com/home/three-tips-psychology-docu...
[deleted]
Don't focus exclusively on improving your text. Supplement your writing with pictures or diagrams to support your idea or process.
All good writing is about narrative. What a compelling narrative means is different for a technical document and a mystery novel, but narrative is the bedrock.
So make sure that things are motivated, and try to not just tell the reader the facts, but take them on a journey such that they will wind up with the right facts AND the right mental model at the end of things.
So make sure that things are motivated, and try to not just tell the reader the facts, but take them on a journey such that they will wind up with the right facts AND the right mental model at the end of things.
- read your writing aloud (it _really_ helps to improve it) when you review it
- just write and then edit - better to have written something (even if it's not great) and then make it better. Especially in writing perfect can be the enemy of good.
- step away - sometimes it helps to review your writing after maybe 1 hour or a day or a few days
- READ MORE - reading well written stuff really helps
- just write and then edit - better to have written something (even if it's not great) and then make it better. Especially in writing perfect can be the enemy of good.
- step away - sometimes it helps to review your writing after maybe 1 hour or a day or a few days
- READ MORE - reading well written stuff really helps
> just write and then edit - better to have written something (even if it's not great) and then make it better.
Related: Do not be precious about what you've written as you rewrite. "Kill your darlings", as the saying goes.
https://www.masterclass.com/articles/what-does-it-mean-to-ki...
Related: Do not be precious about what you've written as you rewrite. "Kill your darlings", as the saying goes.
https://www.masterclass.com/articles/what-does-it-mean-to-ki...
Check this new book on technical writing for developers.
Docs for Developers: An Engineer’s Field Guide to Technical Writing
https://link.springer.com/book/10.1007/978-1-4842-7217-6
Docs for Developers: An Engineer’s Field Guide to Technical Writing
https://link.springer.com/book/10.1007/978-1-4842-7217-6
If you have an opportunity to do any kind of standards (ANSI, ISO, IETF, etc.) development work, take it! Your colleagues there will help you find every possible ambiguity and infelicity and you may never use the passive voice again.
Read a lot. Best tech writing regardless of domain right now is supreme court opinions. Reasonably accessible, written to be read, usually lucid. Read your own work after a layoff. Read out loud. Write to be read out loud.
Sit down with people from the target audience and let them use the thing you are going to write about. Observe where they struggle. Let them articulate what they are doing and why. You wouldn't believe…
Thanks for all amazing answers! This community is really incredible and I didn’t expect this depth of responses!
What do you do to practice or seek feedback?
I've been fortunate in having a scientific background which required writing a lot of essays, later on papers and a thesis. And a lot of technical and user documentation for software in my career.
As the top poster mentioned, "know your audience". You must pitch your material at the right level for the reader. This doesn't mean dumbing it down. It means not including material which isn't relevant for the discussion at hand, and including material which is relevant. As an example, in some internal documentation for end users, one programmer wrote up details about the I2C bus number and addresses and details of some parts on the bus. Not suitable for user documentation, it's just not relevant at that level. They could have mentioned what the user needed to know e.g. configurable options within the application and their effects upon the device function and behaviour. That could be quite detailed, but it doesn't need to include unnecessary detail about the hardware details.
Structure your documentation to introduce concepts that build on each other in order.
For each topic, write an introduction to provide an overview of the concepts and what you will cover, then go into details with examples in logical order, and then wrap it up with a summary and any relevant conclusions at the end. You're taking the reader on a journey with you through some complex topic and you need to treat it like a story with a narrative. It all needs to fit together as a whole, not just a collection of disjoint factoids.
Have a read through various technical books and see how others structure their writing. See how they break everything down into (volumes!), chapters, sections, subsections and paragraphs, and then look at how you can take the system you are documenting, and break it down in a similar way. In many ways this mirrors breaking down a complex set of requirements into applications, libraries, data structures and functions, and depending upon what you're writing about there may be some commonality there. But you aren't just describing the nuts and bolts, you're describing the whole system, conceptually how it is designed and all fits together as a whole, how it's intended to be used, and bring it together in a logical sequence.
Also, look at effective use of figures and tables. With a few good drawings, even very simple diagrams, you can use them to frame what you'll cover in the text. Likewise with tables, don't write out longhand what can be summarised in tabular form.
Just like doing presentations, effective writing comes with practice. And help with review and proofreading will help greatly to spot and improve weak areas. I was lucky to work with a technical writer in my previous job, and she greatly improved the writing technique of many of the software developers on our team. It's a shame that it's not highly prized in software development, because it's an essential tool for effective communication of ideas, and it's a big part of what we should be delivering to our end users and other developers.
As the top poster mentioned, "know your audience". You must pitch your material at the right level for the reader. This doesn't mean dumbing it down. It means not including material which isn't relevant for the discussion at hand, and including material which is relevant. As an example, in some internal documentation for end users, one programmer wrote up details about the I2C bus number and addresses and details of some parts on the bus. Not suitable for user documentation, it's just not relevant at that level. They could have mentioned what the user needed to know e.g. configurable options within the application and their effects upon the device function and behaviour. That could be quite detailed, but it doesn't need to include unnecessary detail about the hardware details.
Structure your documentation to introduce concepts that build on each other in order.
For each topic, write an introduction to provide an overview of the concepts and what you will cover, then go into details with examples in logical order, and then wrap it up with a summary and any relevant conclusions at the end. You're taking the reader on a journey with you through some complex topic and you need to treat it like a story with a narrative. It all needs to fit together as a whole, not just a collection of disjoint factoids.
Have a read through various technical books and see how others structure their writing. See how they break everything down into (volumes!), chapters, sections, subsections and paragraphs, and then look at how you can take the system you are documenting, and break it down in a similar way. In many ways this mirrors breaking down a complex set of requirements into applications, libraries, data structures and functions, and depending upon what you're writing about there may be some commonality there. But you aren't just describing the nuts and bolts, you're describing the whole system, conceptually how it is designed and all fits together as a whole, how it's intended to be used, and bring it together in a logical sequence.
Also, look at effective use of figures and tables. With a few good drawings, even very simple diagrams, you can use them to frame what you'll cover in the text. Likewise with tables, don't write out longhand what can be summarised in tabular form.
Just like doing presentations, effective writing comes with practice. And help with review and proofreading will help greatly to spot and improve weak areas. I was lucky to work with a technical writer in my previous job, and she greatly improved the writing technique of many of the software developers on our team. It's a shame that it's not highly prized in software development, because it's an essential tool for effective communication of ideas, and it's a big part of what we should be delivering to our end users and other developers.
Write
Write more
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