See the entire conversation

Which work(s) would you suggest on writing comprehensible English technical review documents? As a non-native speaker, I would like to improve my technical writing skills. #amediting @handcoding Suggestions for philosophical works on this field are also much appreciated.
16 replies and sub-replies as of Aug 15 2022

I’ve got you covered! Thread incoming in a few minutes. ✊🏻 PS While there’s nothing wrong with cc’ing my @handcoding account, it so happens that my @FriendlyAshley account is more focused on words and language? Anyhoo—it’s all good! Thread in a bit.
While not quite addressing technical writing in particular, S. I. Hayakawa's 'Language in Thought and Action' remains an insightful treatment of the powers and perils of the English language . . .
Here are eight things that I can recommend for making your technical writing more approachable and easier to understand: 1. When you’re about to write something, imagine that you’re at a backyard barbecue and you’re just chatting to a neighbor about that topic… (Cont’d) [1/9]
While you imagine what you’d say, you might try recording this pretend conversation with your phone. Then—write down those exact words. This works because many people instinctively fall back on stuffy habits when writing, and this exercise can help you break out of that. [2/9]
2. If you haven’t watched it recently, you might also check out my talk from @FronteersConf, “1Up Your Writing with Plain Language.” ⤵ And the slides from my talk are also online: handcoding.com/presentations/… [3/9]
3. Use contractions just as often as you would when talking to clients over the phone or voice chat. Using contractions—such as “don’t,” “didn’t,” and “it’s”—offers some of the best bang for your buck toward making your writing more approachable. stroppyeditor.wordpress.com/2015/10/12/con… [4/9]
Contractions: which are common and which aren’t?
Contractions – “you’re”, “we’ll”, “can’t”, “don’t” etc. – generally make language sound less formal, and avoiding them makes it more formal. Over the years, contractions have become more acceptable…
stroppyeditor.wordpress.com
4. Use pronouns like “you,” “I,” and “we” in the same way that you would when you’re talking to someone in real life. ✘ “The aria-invalid attribute conveys if a field is invalid.” ✔︎ “You need to set aria-invalid=‘true’ on invalid form fields.” plainlanguage.gov/guidelines/aud… [5/9]
plainlanguage.gov | Address the user
Plain language makes it easier for the public to read, understand, and use government communications.
plainlanguage.gov
5. Replacing long words with shorter alternatives can also go a loooong way toward making your writing easier to understand. ✘ “We’ll commence testing tomorrow.” ✔︎ “We’ll start testing tomorrow.” This page offers lots more plain alternatives: plainlanguage.gov/guidelines/wor… [6/9]
6. I can also vouch for some specific entries in the book “Garner’s Modern English Usage.” bookshop.org/books/garner-s… The book is a bit thick (shown below, pen for scale), but most entries are no longer than a page. And you can also get it as an app: apps.apple.com/us/app/garners… [7/9]
7. I particularly recommend these entries: • Key to the Language-Change Index (p. xxxi) • And (p. 48] • And/Or (p. 50) • Be-Verbs (p. 113) • But (p. 133) • Conjunctions (p. 204) • Formal Words (p. 406) • However (p. 472) • Obscurity (p. 643) (Cont’d) [8/9]
Recommended Garner entries cont’d: • Of (p. 647) • Prepositions (p. 723) • So (p. 841) • Superstitions (p. 877) • Very (p. 943) • Zombie Nouns (p. 983) 8. And lastly, it can’t hurt to follow me (@FriendlyAshley), though I think you’ve already got that part covered! [9/9]
Thank you so much!
It’s my pleasure! And just to add—within the thread, I think that I may have potentially undersold how awesome Garner’s book is? It’s a real gem, and I can’t recommend it highly enough to folks who are interested in making their writing more approachable. 💯
Thanks for all the tips, Ashley. Very helpful. Have you published them in a blog post I can refer people to? Useful tips for everyone, not only folks on Twitter.
I totally do this one!
Heck yeah—you got this!