Basic technical writing Example

Following is an example for basic technical writing.

The highest priority in technical writing is clarity

While long sentences do not necessarily make bad writing, they are very good at concealing confused ideas. Beginners must practice to write short sentences. Say only one thing at a time. E.g. beginners should avoid sentences like this:
“The result is excellent because the accuracy of the forecast was 60%, which was high.”

Here, I am not going to judge whether the above statement is correct or not. I am focussing on the writing style.

Beginners should write:

“Table 1 shows that accuracy was ((20+80)/200=) 60%. This is a high value for accuracy. Therefore, this is an excellent result.”

Breaking down complex sentences

To a beginner, a good practice is to break down a complex sentence into simple statements. The original text was broken down into three statements above:

  1. Table 1 shows that accuracy was ((40+80)/200=) 60%.
  2. This is a high value for accuracy.
  3. Therefore, this is an excellent result.”

Short sentences are easier to examine

By breaking down a long sentence into short statements, the author will be able to examine the robustness of each statement (this will be elaborated below). Therefore, writing short sentences helps to avoid confusion.

In the above example, Statement (1) states a fact. The author must make sure that this fact is correct. The author must also make sure that this statement is clear to the reader. For example, if the author doubts whether this statement is clear to the reader, it could be expanded to something like this:

“Table 1 shows the confusion matrix of the forecast. Row 1, Column 1 shows the “true negative”, which is 40. Row 2, Column 2 shows the “true positive”, which is 80. Accuracy of the forecast is therefore (40+80)/200 = 60%.”

Here I assume that terminology in “confusion matrix” were explained before this statement. If not, the author must make sure that it is. Besides, the author must not assume that the readers always see what the author wants them to see in tables and figures. It is a good idea to guide the readers by referring to indices and values in the table or figure.

Statement (2) is an interpretation of the results. An interpretation can be challenged. In this case, the reader could challenge whether 60% is a high value for accuracy. To support this interpretation, the authors might want to expand the sentence to something like this:

“Tsang (2014) suggested forecasting in this application is next to impossible. Any forecast that produces accuracy significantly above 50% should be considered excellent.”

Statement (3) must be a logical conclusion from Statement (2). In this case, the readers could challenge whether “a high value in accuracy” implies “excellent result”. The author may want to cover potential challenges like this.

Treat technical writing like a mathematical proof

Make sure that every statement is supported by (a) facts; (b) assumptions; or (c) other supported statements. In this case:

Remarks

The advice here is given to beginners only. The emphasis here is clarity. When an author masters the technique of technical writing, he/she will be able to add his/her own style to make the writing more attractive to read.

Related document: Basic principles of technical writing

The above advice is given by Edward Tsang; last updated 2018.04.02