71–80 of 162 posts
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…
Earlier quoted context omitted.
> 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…
> 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?
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.
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…
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.
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…
Earlier quoted context omitted.
> 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…
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.
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.
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 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 flo…
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.
clearly mark twain took the orwell advice to heart.