21–30 of 42 posts
For prose, replace all common adjectives by more specific or descriptive one, or even remove them too and describe properties. For example: The F-35 passed by my house. When I heard its sound, the jet had already disappeared at the horizon. (This describes super-sonic speed without an adjective or an overly precise speed number.)
Edit: past perfect based on comment
Earlier quoted context omitted.
Some times, the writers don't want to repeat themselves because they were taught that it's "poor writing." And I'd agree, maybe, in (some) prose. But in tech docs, please, repeat yourself instead of using "this", "that", "those", etc., even when perfectly non-ambiguous. This should be preferred "The service is now ready. To check the service's status, ..." over this "The service is now ready. To check its status, ...…
I found your last paragraph entirely unambiguous at all three levels, which led me to disgree with your overall point. Before that I was with you!
Is when someone needs to amend this sentence later, e.g. inserting another point:
"The service is now ready. This means you can query the health endpoint. To check the service's status, ..."
It makes the writing less likely to become ambiguous.
Most documents I see in work will constantly have sentences added/removed as things change.
For technical writing, journalism, etc., one can follow the simple rule no adjectives . For prose, replace all common adjectives by more specific or descriptive one, or even remove them too and describe properties. For example: The F-35 passed by my house. When I heard its sound, the jet had already disappeared at the horizon. (This describes super-sonic speed without an adjective or an overly precise speed number.)…
Same applies to the article - it’s riddled with grammar mistakes. “Lot of your readers may not have English as their first language.”
“test platform that let’s anyone run”
I'd add "don't use demonstratives, like 'this' and 'that', repeat the clause". Sometimes, "that" is ambiguous, leading to unclear writing. E.g. "The foo program is running on the bar server. Who is in charge of that?" vs "The foo program is running on the bar server. Who is in charge of the bar server?"
There are two problems with using ‘this’: Firstly, there may be ambiguity in what ‘this’ refers to. If a paragraph starts with ‘this means…’ or similar, it is impossible to understand the paragraph without looking back through the text – which of course makes it hard to dip into a text (e.g. especially in non-fiction, where readers may dip in to find some specific fact). Furthermore, any unit of text starting with ‘this’ cannot be copied and pasted somewhere else (e.g. from the main body of a report into the conclusions), where the meaning of ‘this’ is completely lost.
I think the problem sometimes happens because the author is writing in a flow state (they are ‘in the zone’) and is creating text that relates to their current mental model of something. This mental state is of course not accessible to a reader, or perhaps not even to the same author at a later date.
Solutions include getting an independent review by someone who isn’t also involved in the writing process, or if this is impossible, reviewing the text yourself after leaving it alone for a while. The ‘this at the start of a text unit’ problem is analogous to a linting check and doesn’t need to be done by a domain expert.
I'd add "don't use demonstratives, like 'this' and 'that', repeat the clause". Sometimes, "that" is ambiguous, leading to unclear writing. E.g. "The foo program is running on the bar server. Who is in charge of that?" vs "The foo program is running on the bar server. Who is in charge of the bar server?"
Some times, the writers don't want to repeat themselves because they were taught that it's "poor writing." And I'd agree, maybe, in (some) prose. But in tech docs, please, repeat yourself instead of using "this", "that", "those", etc., even when perfectly non-ambiguous. This should be preferred "The service is now ready. To check the service's status, ..." over this "The service is now ready. To check its status, ...…
Yes! As you say, it massively depends on whether you are writing fiction or non-fiction. In any sort of formal document, especially technical reports, etc, the reader should never have to spend time working out what the author means. I used to be a doc reviewer in a previous life, and lost count of the number of times docs used different terms to mean the same thing, especially where multiple authors were involved, or a single author was writing different sections at different times.
General plea: If you value your readers, please, please get someone else to check a doc to look for these sorts of problems. If multiple authors are involved, always get someone on the team (a lead author?) to do this check even before submitting it for formal review.
On Writing Well by Zinsser is my favorite book on nonfiction writing. 10/10 recommend to folks who'd like to work on their writing.
Invest in improving your writing skills. It will pay dividends in every aspect of your business.
For technical writing, journalism, etc., one can follow the simple rule no adjectives . For prose, replace all common adjectives by more specific or descriptive one, or even remove them too and describe properties. For example: The F-35 passed by my house. When I heard its sound, the jet had already disappeared at the horizon. (This describes super-sonic speed without an adjective or an overly precise speed number.)…
“Had already disappeared” :) if you’re going to give writing advice, try to give examples without missing verbs. Same applies to the article - it’s riddled with grammar mistakes. “Lot of your readers may not have English as their first language.” “test platform that let’s anyone run”