This is the most valuable piece of advice I hope most readers will take from this article for their technical writing.
This is the most valuable piece of advice I hope most readers will take from this article for their technical writing.
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.