Use Case and the Importance of Storytelling in Technical Documentation

© 2010 Ugur Akinci Software and hardware developers are well-educated intelligent engineers who usually have no difficulty at all in creating products. The real difficulty in product development is not the question of “how” (as in “how can we build this?”) but “what” (as in “what shall this product do?”). Just like in screenwriting, the…

Read More

Write Your Technical Documents with Consistent Tense

© 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]…

Read More

Write Your Technical Documents in Consistent Case

© 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…

Read More

Write Your Technical Documents with Consistent Voice and Mood

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)…

Read More

Use Parallel Construction in Technical Writing, whenever possible

© 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…

Read More

Eliminate "Variance" from Your Technical Writing

© 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…

Read More