Technical Writing made easier

by Bernhard Spuida

1. Introduction

Technical writing requires clarity of expression and therefore simplicity of language. Technical writing is intent on expressing certain key concepts so that these may be understood as easily as possibly by the intended readers — be they programmers or users. Writing in a clear, concise manner makes not only understanding the text easier for the reader; it also makes your life as a writer of technical documentation easier — especially when you are not a native speaker of English.

When talking about algorithms, or sequences of events in a program, absolute clarity of writing is not only needed in the code discussed; but also in documenting this particular program for our fellow programmers and users. We need to attain the same level of clarity of expression in both cases, otherwise readers will to turn to other programs, which are more accessible on the level of understanding and therefore easier to use or extend.

In this short guide, we will cover some of the basic concepts that lead to good (technical) writing. You will certainly discover more such rules and concepts as you practice the writing skills gained out of this set of notes. And also, read! Read a lot, and read varied writing, conscious of the ways language is used in the texts you read. Have your own writing read and criticized by friends and fellow professionals. Pay attention to these criticisms.

You will see that our colleagues, just like the computers we program, require a specific syntax to be adhered to if we want our instructions to be understood. And as in programs, human language text may be straightforward or convoluted, leading as in programs to variations in performance. So here we go.

As this is intended to be a 'work in progress', additions will be made whenever necessary. I am also always happy to receive suggestions and feedback.