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.
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:
- Instructions on how to achieve technical tasks.
- Reports about using new technologies.
- Reports about strengths and caveats on approaches and tools.
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.
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:
- Check all the implications ("because", "hence", "since").
- Focus on facts not value judgement.
- Criticize documents, not people.
- Monitor quantifiers ("for all", "exists", "always" "never")
- Check that all the elements of a list belong to the same kind.
- Avoid the use of first person, unless relevant.
The third draft should focus on motivating our audience to read what we have to say.
At the beginning of our texts we should:
- Explain what is the subject matter and state our objectives.
- Summarize the results of what we want to say.
- Point out conflicts with existing materials.
Adding the motivation should not impact on truth or clarity.
This document is sourced from the wisdom of https://www.uts.edu.au/staff/barry.jay