Quick and Simple Advice for Technical Writing

Spell Check

Spell check your document. It's quick and easy and no reason not to do it.

Make the Reader Quickly Interested

Tell the reader why what they will read is interesting. Keep different people in mind (specialists and those from other fields, theoretically and system oriented people).

Therefore, never forget to mention your contributions.

If you are writing something, hopefully there is a technical reason for it (and there can be many reasons). Identify the top reasons why the document is interesting and emphasize them.

Opening Sentences

Begin each paragraph with a sentence summarizing the point of the paragraph in simple words. Then continue by elaborating the point in a natural order to make it clear.

This way, a reader will

  • know why to read this paragraph and what to expect
  • will be able to skim the document quickly to find the interesting parts

Passive and We

Avoid essentially all uses of passive!

Make sure to correctly indicate who performs the action.

Use “we” or “I” when it really refers to authors of the manuscript. For example, if an algorithm/system does something, then write algorithm/system.

Write Clearly

In general, no need to sound very formal. Just write what is going on in simple, technically correct words.

Two-Phase Writing

Make sure the material is clear to you before you write it, if possible (e.g., make sure you understand what you did).

Often, however, the process of writing will make the material clearer to you. Therefore, you will often want to just write something, and then go back and correct it. This is typically much easier than trying to immediately write the perfect text, and is a vaulable way of eliminating the technical counterpart to Writer's block.

Use an Example

Pick an example document that is close to what you wish to write and feel free to follow the structure of this document.

(Never attempt to copy actual sentences, this is plagarism and is not productive anyway.)