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…
Ask HN: How to level up your technical writing?
41–50 of 162 posts
Re: Ask HN: How to level up your technical writing?
#42I 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.
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.
Re: Ask HN: How to level up your technical writing?
#43Blogging & 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.
Re: Ask HN: How to level up your technical writing?
#44I'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.
Re: Ask HN: How to level up your technical writing?
#45Since 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.…
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).
Re: Ask HN: How to level up your technical writing?
#46I 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…
Re: Ask HN: How to level up your technical writing?
#47Find 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 c…
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.
Re: Ask HN: How to level up your technical writing?
#48Tech 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…
> 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.
Re: Ask HN: How to level up your technical writing?
#49Strunk 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.
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.
Re: Ask HN: How to level up your technical writing?
#50In 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.