All documentation should be written in clear, navigable prose. These principles concern the strategies, tactics, and contexts to consider when defining and organizing technical content.
It’s not enough to educate your audience; documentation should center on helping readers accomplish their goals.
Attention is expensive. Give the answer the reader wants right away.
The big picture must come before the details. Readers learn faster once they have a grasp on the story and its context.
Consider whether documentation is the correct (or only) place for certain types of information. Critical changes to a process or a codebase, for example, should also be broadcast to stakeholders.
What is the actual content of the message, and is each sentence necessary to impart that information?
Not everything should be explained. Explanation should be used to direct readers to key points, and to reinforce those points.
FAQs can signal poor documentation. Anticipate questions and make sure their answers are prominent, clear, and complete.
Consider neural traction: how do you get the information to stick? For example, people identify with material terms more than with abstract terms. Visual words like “red” and “house” fire more neurons than abstract words like “interface” or “structure” because a large percentage of the brain is devoted to visual processing. When constructing examples, include terminology that engages the sensorium (the sensory apparatus or faculties considered as a whole). Familiar references can have the same effect: they can give the reader the purchase necessary to focus on novelty (i.e. the subject of the documentation). Similarly, limiting the use of pronouns frees up the reader’s working memory.
Are you trying to persuade someone to select your API over others, or are you assisting someone debugging a function? How does the rhetorical strategy change if you need to target both audiences?
When done well, the process of documentation can illuminate problem areas, and generate ideas for improvement. Put channels in place to make use of that feedback.