Larry McEnerney’s lecture The Craft of Writing Effectively:
Ask HN: How to level up your technical writing?
21–30 of 162 posts
Re: Ask HN: How to level up your technical writing?
#22What do you do to practice or seek feedback?
Re: Ask HN: How to level up your technical writing?
#23Strunk 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.
Re: Ask HN: How to level up your technical writing?
#24Tech 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.)
Re: Ask HN: How to level up your technical writing?
#25Start 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
Re: Ask HN: How to level up your technical writing?
#26Since 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/
Re: Ask HN: How to level up your technical writing?
#27I 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.
Re: Ask HN: How to level up your technical writing?
#28Strunk 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.
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.
Re: Ask HN: How to level up your technical writing?
#29Larry McEnerney’s lecture The Craft of Writing Effectively: 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.
Re: Ask HN: How to level up your technical writing?
#30Tech 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…
> 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.