Live data from Hacker News

On Writing Well

zodvik.com

41–42 of 42 posts

Re: On Writing Well

#41
post #3

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?"

Another thing worth pointing out is that technical texts are rarely read entirely as a literary piece, so repeating things is a welcome thing. As someone who spends great part of the day reading datasheets it is specially annoying having to scan through the entire piece to see what something means like for example acronyms:

“The setting of these bits is only valid if the BCST bit in FBCSTAT is 1, while the FRDY bit in FSTATR is 1.”

Re: On Writing Well

#42
post #37

I hope I’m not the only one who cringes at the “asks” terminology, in the context of “writing well”.

Yeah, ironically in a post on writing well, the author turns a verb into a noun and then uses it to mean both "questions" and "requests".
Post reply on HN