#1 Determine Target Audience

Define a target audience and what they will learn from your document.

#2 Put it in Context

Position your documents relative to the overall system.

Possible contexts are:

#3 Be formal, if you must

Write as formal as necessary and not a bit more.

Technical contracts between systems (web services, libraries) and technical designs require formality. All other documents typically benefit from simple, informal writing.

#4 Chose the Right™️ Medium

Chose a medium/tool appropriate to the content, audience and formality.

Examples of the Right™️ Medium

#5 Version the document if necessary