From c5650708a7f35c59a096e1c03ec6989fbfedffce Mon Sep 17 00:00:00 2001 From: Astrid Elocson Date: Fri, 26 Dec 2014 19:32:01 +0000 Subject: [PATCH] Create Technical Prose Style.tid --- .../tiddlers/about/Technical Prose Style.tid | 15 +++++++++++++++ 1 file changed, 15 insertions(+) create mode 100644 editions/tw5.com/tiddlers/about/Technical Prose Style.tid diff --git a/editions/tw5.com/tiddlers/about/Technical Prose Style.tid b/editions/tw5.com/tiddlers/about/Technical Prose Style.tid new file mode 100644 index 000000000..0f8f7465b --- /dev/null +++ b/editions/tw5.com/tiddlers/about/Technical Prose Style.tid @@ -0,0 +1,15 @@ +created: 20141226192500000 +title: Technical Prose Style +tags: documenting + +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. "Execution of the macro is performed" just means "The macro runs". "Your expectation might be..." just means "You might expect..." + +Prefer the active voice by default: "Jane creates a tiddler" rather than "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: "a tiddler is created". But it may be clearer to proceed from cause to effect and say "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.