Characteristics and types of Technical Writing

In this lesson, we'll go over the characteristics of technical writing, the different types of technical writing you'll encounter as a developer, and some types of communication that benefit from technical writing best practices. We'll also contrast technical writing and business writing.

Characteristics

Unlike other forms of writing, technical writing should be:

• Audience-oriented: Audience is the name of the game in technical writing. Your audience is not just reading what you are writing, they are also the reason you are writing. If what you have written is not understandable to your audience, you have not written your document successfully.

• Accessible: The information contained in technical writing pieces should always be clearly understandable by its intended audience. It is important to note that the piece doesn’t need to be understood by everyone, only your intended audience.

• Comprehensive: Technical writing must include all relevant information. It is important to lead someone to the same understanding as you if they do not have all the information you have. This means that you should not include irrelevant information, only include that which is required for your audience to understand the topic at hand.

Successful documentation is both comprehensive and clear. It must have both elements to be best received by your target audience.

• Logical: Information should be structured with the information most relevant to the reader at the beginning and then broken down throughout the text. Keep in mind that your writing must remain comprehensive. Comprehensive writing is closely related to structure as it is very important that your writing is presented in a way that is easy for your audience to understand.

• Clear: Clear documentation means that it is easy to understand and your reader is not left confused or with questions. Please note that “clear” is also dependent on your audience. What is clear to a nontechnical person may not be the same as what is clear to a developer. Always define your audience first and cater the clarity of your documentation to them specifically. A good rule of thumb is to use simple, straightforward rhetoric.

• Concise: Concise means your documentation is straight to the point. There is no frill and no irrelevant information. Your document only deals with the matter at hand.

• Accurate: The information you are presenting in your documentation needs to be well-researched and factually correct. If you are presenting statistics or data, make sure that what you are presenting is correct so that you are not misleading your reader.

• Impersonal: Impersonal means that you, the writer, avoid any “I” or “me” pronouns, and use pronouns like "one," "you," or "they" instead. Technical writing sticks to facts and is never opinionated.

The pronoun "we" should be avoided when possible, but (if necessary) it can be used to refer to the actions that you and your team were required to do.

Software documentation