For anyone interested in the topic, I would recommend reading this article:
https://www.americanscientist.org/blog/the-long-view/the-sci...
On Writing Well
11–20 of 42 posts
Re: On Writing Well
#12For Technical Writing, follow "The Minto Pyramid Principle" (https://untools.co/minto-pyramid/), keep everything Concise, Precise, use Assertive/Definitive voice and show Usage with Examples in the beginning itself.
Re: On Writing Well
#13For Technical Writing, follow "The Minto Pyramid Principle" ( https://untools.co/minto-pyramid/ ), keep everything Concise, Precise, use Assertive/Definitive voice and show Usage with Examples in the beginning itself.
At Stripe, this was also framed as BLUF - bottom line up front.
Re: On Writing Well
#14Just going by the title, I thought this was going to be related to William Zinsser's book of the same name. It's not, though of course many of the topics are shared between the two.
It's been a few years since I've returned to it, but the material in Zinsser's book has been useful to me as an engineer that has to occasionally write for both fellow engineers and non-technical folks. I would recommend Zinsser's book if you like the content in the article and wouldn't mind a bit more.
Re: On Writing Well
#15For Technical Writing, follow "The Minto Pyramid Principle" ( https://untools.co/minto-pyramid/ ), keep everything Concise, Precise, use Assertive/Definitive voice and show Usage with Examples in the beginning itself.
At Stripe, this was also framed as BLUF - bottom line up front.
BLUF is a Military standard; see article linked to under the "sources" section of the above link.
Re: On Writing Well
#16Just going by the title, I thought this was going to be related to William Zinsser's book of the same name. It's not, though of course many of the topics are shared between the two. It's been a few years since I've returned to it, but the material in Zinsser's book has been useful to me as an engineer that has to occasionally write for both fellow engineers and non-technical folks. I would recommend Zinsser's book if…
Author here. TIL about the book.
For reference https://www.goodreads.com/book/show/53343.On_Writing_Well
Re: On Writing Well
#17I'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…
I want you to know that¹ I enjoyed reading this comment, more than just an upvote could convey.
¹ ;)
Re: On Writing Well
#18I'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, ...…
We should write with *pointers.
Re: On Writing Well
#19https://developers.google.com/tech-writing covers the same topics in more detail.
Re: On Writing Well
#20Also, get a copy of Strunk & White's "The Elements of Style" and read it often.