When writing an [[instruction tiddler|Instruction Tiddlers]], start by planning a route through the information you wish to present. This should be a simple, logical, direct progression of thoughts, with no backtracking or forward references. Use this approach even within individual sentences: always proceed from cause to effect, from the old or known to the new or unknown.
Keep sentences short and simple. A clear technical sentence seldom contains more than one idea. It therefore avoids parenthetical information. Similarly, keep paragraph structure simple. A flat presentation is often easier to understand than a hierarchical one.
It is often possible to simplify a sentence without changing its meaning, merely by adjusting its vocabulary or grammatical structure. <<.word "Execution of the macro is performed">> just means <<.word "The macro runs">>. <<.word "Your expectation might be...">> just means <<.word "You might expect...">>.
Prefer the active voice by default: <<.word "Jane creates a tiddler">> rather than <<.word "a tiddler is created by Jane">>. The passive voice can be useful if you want the reader to focus on the action itself or its result: <<.word "a tiddler is created">>. But it can often be clearer to proceed from cause to effect and say <<.word "this creates a tiddler">> in the active voice.
Documentation often presents two items that are parallel either by similarity or by difference. The reader will more easily detect such a pattern if you use the same sentence or phrase structure for both. But this must be balanced with the need to avoid monotony.
Prefer precise instructions over woolly descriptions. If something has a name, use it. If something lacks a name, give it a tiddler.
