WingNews logo WingNews GitHub [2]
top | item 31859040

Ask HN: How to level up your technical writing?

295 points| maxekman | 3 years ago | reply

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

158 comments

order
[+] marcpaq|3 years ago|reply
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.)

[+] ChrisMarshallNY|3 years ago|reply
> 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.

[+] ducharmdev|3 years ago|reply
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.

[+] pieno|3 years ago|reply
> 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.

[+] k__|3 years ago|reply
Grammarly is still better than no editor.
[+] Gaessaki|3 years ago|reply
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.

[+] Gaessaki|3 years ago|reply
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.
[+] Brystephor|3 years ago|reply
> 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.

[+] gnat|3 years ago|reply
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/...

[+] raybb|3 years ago|reply
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."

[+] rg111|3 years ago|reply
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™.

[+] mishftw|3 years ago|reply
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...

[+] bombcar|3 years ago|reply
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.

[+] jacksnipe|3 years ago|reply
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.
[+] maxekman|3 years ago|reply
Love your tip of how to structure a text. Thanks!
[+] MrPowers|3 years ago|reply
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.

[+] warrenm|3 years ago|reply
> 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

[+] nicbou|3 years ago|reply
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.

[+] Tomte|3 years ago|reply
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.

[+] maxekman|3 years ago|reply
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.
[+] supersrdjan|3 years ago|reply
I came in to write exactly what you wrote. +1
[+] sateesh|3 years ago|reply
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.
[+] vnorilo|3 years ago|reply
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...

[+] ghaff|3 years ago|reply
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.
[+] kashyapc|3 years ago|reply
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/

[+] ghaff|3 years ago|reply
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).

[+] DonHopkins|3 years ago|reply
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.

[+] sasaf5|3 years ago|reply
And on the next iteration, change the column width a little.
[+] eatonphil|3 years ago|reply
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.

[+] _sohan|3 years ago|reply
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.

[+] DoreenMichele|3 years ago|reply
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.

[+] maxekman|3 years ago|reply
Really good suggestion, I have not been very active commenting here. Thanks!
[+] captainkrtek|3 years ago|reply
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.

[+] ghaff|3 years ago|reply
>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.

[+] gautamdivgi|3 years ago|reply
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).

[+] klodolph|3 years ago|reply
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.

[+] inphovore|3 years ago|reply
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.)

[+] Fricken|3 years ago|reply
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.
[+] maxekman|3 years ago|reply
Good suggestion! Do you have any technical docs that stand out as extra good in your opinion?
[+] christophilus|3 years ago|reply
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.