about · lately · live · notes · talks · writing · contact · thanks · support ·


technical writing
Plato’s Socrates asks Gorgias “with what class of objects is rhetoric concerned?”
For example, a doctor must know medicine and the body, a lawyer must know the law
in order to offer rational explanations (logos) regarding their expertise. 
Plato asks upon what foundation rhetoric rests
Gorgias rhetoric is an "art concerned with words"
Socrates: What does good rhetoric produce? Because all good art must have some good results ...

This document introduces a three draft model for technical writing.

The goal is to maximize the benefits of sharing knowledge within the team.

The objective is to ensure that information is true, clear, and has the right intent.

The three draft model for technical writing is not meant to be followed as we write each paragraph rather it is meant to be applied as layers upon a complete raw set of ideas captured as text (draft zero).

Each draft is a complete pass over a document.

truth

The first draft should focus on truth.

As engineers when we do technical writing we are in the truth business.

We exchange truths for mutual benefits:

Sharing false, partially false or incomplete information diminishes the benefit of the information exchange. Therefore we must think about technical writing with terms as logical propositions where each sentence is either true or false.

We must check that all sentences are true.

Even if all sentences are true there is room for improvement.

If a sentence can be simplified while remaining true then the simplified statement is usually preferable and usually stronger.

clarity

The second draft should focus on clarity.

The goal is to make all our sentences clear to our ideal reader; in this case our team members.

All unexplained words, approaches or attitudes must be explained.

The goal is to make all sentences clear to our readers while maintaining the truth.

There are a few tricks that can help to make sure an argument is clear:

motivation

The third draft should focus on motivating our audience to read what we have to say.

At the beginning of our texts we should:

Adding the motivation should not impact on truth or clarity.

acknowledgements

This document is sourced from the wisdom of https://www.uts.edu.au/staff/barry.jay