Ask HN: Looking for resources to improve my technical writing
I'm looking for resources – ideally books, but open to other media – that will help me become a better writer. Specifically, I want to write decent technical documentation, guides, and tutorials. Is there anything out there that can breathe a bit of life into my dull, repetitive attempts at technical articles?
3 comments
Do you want to be a better writer, or do you want to make your writing more interesting? Because these are actually orthogonal things.
A _good_ writer never uses flowery or verbose prose and avoids passive voice. To paraphrase whoever it was, "perfection is achieved not where there is nothing left to add, but when there is nothing left to take away." Write profusely, edit mercilessly. If you're new to writing, it won't be unusual to entirely re-write a piece two or three times before it doesn't suck. It _does_ get easier but it takes a lot of work and patience to get there.
I'll assume from your last sentence that you want to make your writing more interesting. To me, a piece of writing is interesting if it doesn't take itself too seriously and sprinkles in a few jokes and jabs here and there. When I'm writing something for a general audience online, I imagine I'm writing it for a friend and wish to reward the reader for their attention with some light humor, if I'm able to find the torch.
Some writers are literally terrified of using first-person singular pronouns for some reason. It's always, "we did this thing," or "our favorite movie is X," or "you can thank us by blah blah blah." Even YouTubers do this when it's patently f'n obvious there's only person behind the camera and it drives me goddamn insane. Don't do this, is probably what I'm trying to say. The editorial "we" is to be reserved for when you _actually_ represent more than one person, like a group research project, or a whole magazine.
Is there a particular style you want to emulate? If so, read everything you can in that style. I greatly enjoy the writing of Sir Terry Pratchett and will consider my life a resounding success if I ever manage to be 1/10th as clever as him. I also recommend Dave Barry and literally everything written by James Mickens. If you find an author you like, don't just read them, actually analyze their writing. Study what makes it "work" for you.
A _good_ writer never uses flowery or verbose prose and avoids passive voice. To paraphrase whoever it was, "perfection is achieved not where there is nothing left to add, but when there is nothing left to take away." Write profusely, edit mercilessly. If you're new to writing, it won't be unusual to entirely re-write a piece two or three times before it doesn't suck. It _does_ get easier but it takes a lot of work and patience to get there.
I'll assume from your last sentence that you want to make your writing more interesting. To me, a piece of writing is interesting if it doesn't take itself too seriously and sprinkles in a few jokes and jabs here and there. When I'm writing something for a general audience online, I imagine I'm writing it for a friend and wish to reward the reader for their attention with some light humor, if I'm able to find the torch.
Some writers are literally terrified of using first-person singular pronouns for some reason. It's always, "we did this thing," or "our favorite movie is X," or "you can thank us by blah blah blah." Even YouTubers do this when it's patently f'n obvious there's only person behind the camera and it drives me goddamn insane. Don't do this, is probably what I'm trying to say. The editorial "we" is to be reserved for when you _actually_ represent more than one person, like a group research project, or a whole magazine.
Is there a particular style you want to emulate? If so, read everything you can in that style. I greatly enjoy the writing of Sir Terry Pratchett and will consider my life a resounding success if I ever manage to be 1/10th as clever as him. I also recommend Dave Barry and literally everything written by James Mickens. If you find an author you like, don't just read them, actually analyze their writing. Study what makes it "work" for you.
Out of my depth here a little. But general writing responds well to knowing/reading good writing. Like the quote “great writers steal” or something like that. Read the greats like Asimov or Feynman. Asimov was of course great for pulling a reader into the work. More directed, analyze your audience. You can pick up the tone of a discipline by reading their magazines and academic journals.
I was assigned “The Elements of Style: The Classic American English Writing Style Guide” by Strunk and White at one point.
If it’s technical documentation, lots and lots of screenshots. Screenshots can outright make words redundant.
Other tricks: get away from it entirely for a period of time. Taking a shower/sleeping or walking can function as a reset. If you’re writing a book or something serious then taking two weeks from reading it will put you in perspective of a first time reader of it (as close as the author can get). Your brain will even continue processing it for a day or two after writing both consciously and subconsciously so going back to it after a stint can be more productive than expected.
I was assigned “The Elements of Style: The Classic American English Writing Style Guide” by Strunk and White at one point.
If it’s technical documentation, lots and lots of screenshots. Screenshots can outright make words redundant.
Other tricks: get away from it entirely for a period of time. Taking a shower/sleeping or walking can function as a reset. If you’re writing a book or something serious then taking two weeks from reading it will put you in perspective of a first time reader of it (as close as the author can get). Your brain will even continue processing it for a day or two after writing both consciously and subconsciously so going back to it after a stint can be more productive than expected.
A big part of learning how to be a better technical writer is to read and critique lots of other technical documents as part of your studies.