[okennedy]

Writing, especially when the intent is to transmit an idea, is a lot like writing code: (i) Make absolutely sure that you know what your goal is (and why it's your goal). (ii) Before you use a term or concept that the reader might not know, make sure you've defined it. (iii) Make sure to state your assumptions.

Like programming, start with the main argument (API) and then work your way backwards: What doesn't the reader know or agree with? What fact/claim would convince them? Why should they believe it? Repeat recursively as needed.

Finally, I have a list of 'weasel words': "this", "that", "it", "these", "them". Words like 'these' are referential, and it's really easy to use 'them' without actually referencing anything (uninitialized pointers?). If you see 'this' in your writing, force yourself to replace 'it' with few words summarizing the referential target.