Introduction to Technical Writing technique

In our company, Briswell, communication is a very common activity at work, whether in verbal or written. Consequently, we often experience misunderstandings or difficulties in conveying and understanding each other’s opinions. To overcome this, we all have participated in a training session called Technical Writing.

So, what is Technical Writing? This is a way of writing that accurately and clearly conveys professional content or technical information to a specific audience. To illustrate, an example in our daily life that uses this writing technique is the user manual when buying things such as refrigerators, washing machines, etc., which we often throw away. It sounds theoretical and is reasonable to be thrown away, isn’t it?

Although I initially had the same mindset, after completing this course, I have learned a few techniques that I believe can improve my communication skill. So, before deciding to throw it away, why don’t we take a look at a few techniques together?

1. Fit documentation to your audience

Each person has different experiences and knowledge, so how they approach the same issue also differs. For example, when explaining the cause of an error to someone with no IT background, the developer might say:

　・Because the file permission is set to 755, this user can’t create a folder.

With this sentence, the person without IT background may not understand what 755 means, and wonder why 755 is related to creating a folder. Therefore, to make it easier for this person to  understand, we can explain by this way:

　・The system is configured that only the owner of a folder can create files within it, and the current user is not the owner of the folder, so they can’t create a sub-folder.

The explanation, although longer, helps someone with no IT knowledge to understand the cause of the error. 

Therefore, in communication, we need to consider what information our audiences already understand and what they do not, so we can have the appropriate way to explain the information.

2. Use terminology consistently

To explain about a screen’s function, the specification is written as below:

　・The system will get the file stored in the upload_file_2024 folder, then display it on the screen. If the user uploads a new file, this file will be stored in the upload_file_2024  directory.

When reading the above specification, are you confused about whether the upload_file_2024 folder and upload_file_2024 directory are the same place? This is because the specification uses terminology inconsistently. We can correct by this way:

　・The system will get the file stored in the upload_file_2024 folder, then display it on the screen. If the user uploads a new file, this file will also be stored in the upload_file_2024  folder.

Thanks to the consistent terminology, “folder”, readers can understand the place to get the file and the place to store the file is the same place. 

Consistent terminology not only helps readers understand the content better but also increases the credibility of the conveyed information.

3. Omit needless words

When speaking, do you usually add emotional words or keep repeating synonyms? In daily conversation, expressing emotion helps the story to be more lively, yet in discussing issues, we have to present as clearly and concisely as possible.

Instead of saying this:

　・Bug fixing was really very slow and time-consuming so it has caused many losses for the customer.

We can say:

　・Bug fixing took a lot of time so it has caused many losses for the customer.

Although the phrase “really very slow” is omitted, the reader can still understand that bug fixing is slow, right? 

Remember that clear sentences can help readers catch the important part of the information and make sentences easier to understand!

Above are three methods that I find helpful in Technical Writing. After reading this, do you want to know more about these techniques? If you have any interest, please refer to the full document compiled by Briswell at the link below! 

Training Technical Writing – Công ty Briswell Việt Nam – Speaker Deck

Reference source:

Technical Writing Courses