Characteristics and Types of Technical Writing

Learn about the characteristics of technical writing and how they come in handy when writing certain types of documentation.

We'll cover the following

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.

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 language.

  • 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

As stated previously, your software documentation requirements will largely depend on the type of methodologyFor example, Agile, Waterfall, SDLC, etc. utilized by your company. However, an overview of the types of documentation that exist are as follows:

Project documentation is made up of product documentation and process documentation:

  • Product documentation details the product in development with instructions on how tasks can be performed with it. It consists of documents like user manuals, release notes, installation and troubleshooting guides, etc.

  • Process documentation focuses on documenting the steps involved in the development process, and the standards and guidelines that ensure a smooth running of the workflow. It consists of documents like training material, quality assurance documents, standards, project documentation, project plans, etc.

During your career, you will probably be asked to create or help to create at least one of the documents listed above. It should be noted that due to the complexity of many technical ideas, there are a variety of templates that can and should be utilized while creating software documentation. Although we won't go through each type of software document in detail, notice which technical writing characteristics are most important for each document and begin to think of how these characteristics may be employed in other types of software documentation. Let's look at some examples from product documentation to better understand this point.

Product documentation

Bug reports

Purpose: Bug reports detail what is wrong and what needs to be fixed. It is important that the document is specific and the reported bug can be reproduced. The report must efficiently communicate the problem to the person who will be fixing the bug.

Audience: Developer(s) who will be assigned to your task. The prior knowledge that this person has of the code will depend on a few factors, such as:

  • If they were recently hired.
  • If they wrote the code.
  • If they have never seen the code before.

If you are unsure, write for the least knowledgeable option. This will ensure that everyone who will potentially read your report can understand.

Technical writing characteristics to utilize:

  • Audience-oriented: In this case, it will be the developer assigned to your task.

  • Clear, logical, and concise: These three characteristics will ensure that your report is understandable to the assigned dev and short enough that the task can be understood and completed with ease.

End-user documentation

Purpose: End-user documentation is an umbrella that covers all guides, manuals, or instructions. The goal of end-user documentation is to explain to the audience how to install, use, or troubleshoot for a product.

Audience: The product’s targeted user. This audience could be technical or nontechnical depending on the product.

Technical writing characteristics to utilize:

  • Audience-oriented and accessible: This is a document that will help your end-user to understand and utilize the product in the way it was intended. You need to make sure that the end-user can achieve that using your documentation. However, if your documentation does not write for the knowledge level and understanding of the intended audience, it doesn't matter how clear the documentation may be to someone at a different level of understanding, the document will not be able to satisfy its purpose.

  • Impersonal: This document is factual and should not include any personal opinion or tone.

  • Clear, comprehensive, and logical: The document must not leave any questions unanswered or inspire new ones. To do this, the content should be comprehensive and include all relevant information in a logical manner that does not confuse your intended audience.

  • Accurate: The documentation must be factually accurate and should not lead your audience in the wrong direction. Such a mistake may cost user engagement and/or decrease the understandability of the product.

Root cause analysis (RCA)

Purpose of document: Used to find the root cause of an event and better understand how to prevent the same situation from happening in the future.

Audience: Stakeholders and fellow developers who are working on the solution to the problem. Enough background must be covered in your document based on the level of knowledge your audience has about the situation.

Technical writing characteristics to utilize:

  • Logical: An RCA needs to be written with a particular flow in mind, covering the why, what, and how of the situation at hand.

  • Accurate: If this document is not accurate, it will not be possible for the root cause to be discovered and a solution to be theorized.

Code documentation

Code comments

Purpose: Increase understandability of code by clarifying why you added a specific line of code that someone else may see as unnecessary, providing source links to copied code, adding comments when code is modifiedperhaps due to a bug fix or some other reason , commenting to mark an incomplete implementation, or when including links to helpful external references.

Audience: Anyone who is working on or reading your code. Your audience may even be you in the future, coming back to update your old code. This audience will be technical.

Technical writing characteristics to utilize:

  • Concise: Code comments should never be lengthy or multiple sentences. They need to sum up what is happening in only a few words or a short statement.

  • Clear: Use clear and precise language when writing code comments. This is not the place for confusing or lengthy words. Be as simple as possible and straight to the point.

Below is an example of how to write code comments.

Press + to interact
# declare a list of integers
numList = [45, 20, 27, 39, 10]
# define a method to find the sum
def findSum(list):
    sum = 0
    for item in list:
        sum += item
    return sum
# call the findSum method
listSum = findSum(numList)
# print the result of the findSum method
print("The sum of numList is", listSum)

README files

Purpose: README files allow developers to see and understand what your project is trying to deliver and how. Think of README files as a proposition to every developer who comes across your project. You want to collaborate with them, now make it clear why they should collaborate with you. Your README files must be up to date and comprehensive enough for a stranger to theoretically come in and work to improve your project in the direction you want it to go without any prior knowledge.

Audience: Your audience for README files will most likely be common developers. Remember, they have no way of knowing what you thought as you wrote each line of code or the direction you want to take the project. So, the content must be comprehensive and clear enough that someone coming to your project/code for the first time can understand.

Technical writing characteristics to utilize:

  • Impersonal: This document should have an impersonal tone to allow the reader to focus on the purpose of your code.

  • Clear: This document must be clear about the purpose and desired outcome, and provide clear guidelines for the project so that another user can jump right into the repository and get to work.

  • Accurate and comprehensive: It is crucial that this document is accurate as incorrect or out of date information may cause another user to make a wrong decision, to the detriment of the code, that they would not have made otherwise. Similarly, if your file is not comprehensive, it will not allow the potential collaborator to understand where you've come from to know where and how you want to go forward.

  • Audience-oriented and accessible: README files should be oriented to anyone who is interested in collaboration (for instance, using platforms like GitHub). This means that they probably have a baseline knowledge of development, but there is no way to know how far that knowledge extends. So, ensure that your file is accessible for your ideal developer. Ask yourself, "Who do I want to collaborate with on this?" Then, write your file accordingly.

  • Logical: Your README file must make logical sense. If a collaborator is excited about your project, but is having trouble understanding the flow of logic in your README file and subsequent guidelines/files, they will become uninterested and move on.

Show off what you've learned! Complete the quiz below.

1

What is the most important characteristic of a piece of technical writing?

A)

Audience-oriented

B)

Clear

C)

Accurate

Question 1 of 20 attempted