3 ms·
> 29. Be sparing with pronouns in technical writing. It's better to repeat a noun than have it be unclear what "it" refers to. This is the most valuable piece
by vaer-k 8y ago
> 29. Be sparing with pronouns in technical writing. It's better to repeat a noun than have it be unclear what "it" refers to.
This is the most valuable piece of advice I hope most readers will take from this article for their technical writing.
- ergothus 8y agoThis advice ("avoid unspecified pronouns") also applies to communicating in text, period. SMS, IRC, Slack, in all of them you can avoid a lot of confusion by being clear in your nouns. BAD: "We're hooking up the refresh token to the API next week. It was broken by a bad commit, but that is fixed" GOOD: "We're hooking up the refresh token to the API next week. The token was broken by a bad commit, but that commit is fixed" This advice is one of the two most important tips for clear communication in text I know of. The other tip is: don't ask an A or !A question - you'll just get "yes" or "no" as an answer. Instead, ask to confirm A and not B. BAD: "Are we releasing this week? Or next week?" GOOD: "We are releasing this week, not next week, right?" This second tip, however, requires a lot more work to make natural.
- LinuxBender 8y agoGreat examples. For the release, I would specify the date, time and timezone.
- tunesmith 8y agoThe A or !A thing never fails. But it's more a hack to work around other people having poor communication skills. It's also good advice to pay attention to the question being asked of you, and actually answer it. So if someone asks you, "Are we releasing this week? Or was it next week?", don't reflexively answer "yes" or "no".