On Writing Well
zodvik.com
On Writing Well
1–10 of 42 posts
Re: On Writing Well
#2[deleted]
Re: On Writing Well
#3I'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?"
Re: On Writing Well
#4I'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, ..."
Re: On Writing Well
#5I'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, ...…
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!
Re: On Writing Well
#6Earlier 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!
Many 'rules' including this one can be broken if you know the tradeoffs and can make the case-by-case choices correctly. But that was a poor example for motivating a behaviour.
Re: On Writing Well
#7[deleted]
Re: On Writing Well
#8[deleted]
Re: On Writing Well
#9[deleted]
Re: On Writing Well
#10I'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?"
Repeating the clause can be useful, but I don’t think it should be used as a general rule. Avoiding ambiguity does not mean forcing repetition and making dull prose. Example:
> The foo program is running on the bar server. Who is in charge of the latter?
Though in general that¹ is still weak. Depending on the surrounding context (which isn’t present in your comment) and the main idea, a possibly better example:
> Who is in charge of the bar server running the foo program?
Without a real use case, we could spend days discussing what is “better”.
Though yes, removing “that” can improve the text, thought that² doesn’t mean you need to replace it with anything. Let’s take the first paragraph in the article:
> Writing a technical document is surprisingly hard. That is not because of the skill to tell a story. It’s because writing forces a level of clarity that is easy to gloss over while thinking through a topic.
An alternative without any “that”:
> Writing a technical document is surprisingly hard. Not because of the skill required to tell a story, but because writing forces a level of clarity otherwise easy to gloss over while thinking through a topic.
¹ I don’t think there’s any ambiguity the “that” is referring to the previous sentence.
² I don’t think there’s any ambiguity the “that” is referring to improving the text.