English

© 2010 Ugur Akinci Most of the time you’ll hear that short is good in technical writing and long is bad. That’s true in general. But like everything else, this rule has an exception as well. If you write in too many short sentences cascading one after the other, the readers will have a hard…

© 2010 Ugur Akinci A consistent technical document is one that instills confidence and trust in end-users. It all starts with a template. It doesn’t matter whether you are creating a book, help file, or a web site. A template is a must. Once you’ve got your template designed and under control, you need to…

© 2010 Ugur Akinci Don’t go time-traveling from one clause to another. If you have multiple clauses in a sentence, try to make sure their verbs are in the same tense. EXAMPLE: “The circuit started to overheat [PAST] when the operator shuts down the relay [SIMPLE PRESENT].” BETTER 1: The circuit started to overheat [PAST]…

© 2010 Ugur Akinci The verbs you use in your technical writing must agrees with the case of your subject(s). For example: The school [Main SUBJECT] where he graduated [auxiliary VERB] from is [Main VERB] the oldest in the country. (School [singular] … is [third person singular]) VIOLATION of the rule: The school where he…

Technical writing is consistent writing, whether you’re writing software or marketing specs. Your sentences need to be consistent in Voice Mood Case Tense Style If you end your sentences with the same mood, voice and tense that you start them with, the battle is already won. [Which rule did this sentence violate already?] Technique 1)…

© 2010 Ugur Akinci Try to write in sentences that have similar syntaxes and components. Construct your sentences and paragraphs with “parallel,” i.e. similar, components. That increases audience comprehension and retention. It makes your technical documents more user-friendly. For example, if you start the first sentence in a  procedural description with an action verb, start…

© 2010 Ugur Akinci “Variance” is an important concept in statistics and plays a crucial role in technical documentation as well. Without getting too technical about it: “variance” denotes the way the values of a set of elements vary around a central mean value. Imagine you weighing a hundred marbles. Let’s say the arithmetic-mean weight…

© 2010 Ugur Akinci Technique: Split long sentences into shorter and simpler ones Here is a sure-fire method to split your long sentences into shorter and more easily understandable ones: Split your sentences at conjunctions like “and”, “or”, “while”, “however”, “although” etc. Those are the connection points where one clause is linked to another. By…

© 2010 Ugur Akinci Technical writing has to be clear, linear, and logical. Technique:  Write in simple sentences that anybody can understand Avoid compound sentences with multiple clauses. Here is the most basic sentence structure in English: SUBJECT + VERB + OBJECT If a sentence does not have this structure, try to rearrange the components…

© 2010 Ugur Akinci Technical writing needs to be correct, before anything else. This is the MOST IMPORTANT sine qua non condition of all technical writing. If a technical document is incorrect, it’s value is zero, nil, zilch. The rest doesn’t matter. Incorrect technical writing creates confusion, misinformation, and even dangerous mistakes and disasters. Technique…