5 Tips for Effective Communication

🛑 Don'ts & ✅ Do's for effective remote communication

Oct 30, 2024

Generated with flux-dev. Prompt: Generate me a water color image where there is red text on beige background. The text should say: “What do you mean?”

Working fully remote for a Silicon Valley startup taught me that day-to-day written communication is as crucial as the code I write.

The clarity of my words can make a difference: a coworker might spend either 1 minute or 10 minutes trying to decipher my message. If this happens multiple times a day, I could save the company hours of work just by writing more clearly.

In this article, we’ll explore some practices for clear technical writing. (For additional tips, check out my previous article.)

Use Shorter Sentences for More Effective Communication

Short sentences communicate more powerfully and are easier to understand than long ones.

🛑 Don’t: The API, which was developed using Python and includes multiple validation layers and error checking mechanisms, processes the user input after ensuring all required fields are present and correctly formatted according to the specification.

✅ Do: The API validates user input before processing the request.

Tip 1: Focus Each Sentence on a Single Idea

Just as a single line of code performs a single task, each sentence should convey one idea.

🛑 Don’t: The authentication system handles user login requests by first validating the provided credentials against the database, then generating a secure JWT token if validation succeeds, and finally returning the token to the client which can be used for subsequent API calls until it expires after 24 hours.

✅ Do: The authentication system handles user login requests. First, it validates the provided credentials against the database. If validation succeeds, the system generates a secure JWT token. The system then returns this token to the client. The token can be used for subsequent API calls and expires after 24 hours.

Tip 2: Eliminate Filler Words for More Direct and Effective Writing

Many sentences contain filler words that add no real value. Cutting these words makes your writing clearer and more impactful.

🛑 Don’t: It should be noted that in order to properly save any changes that have been made, it is necessary for the user to proceed to click on the submit button.

✅ Do: Click the submit button to save changes.

With practice, you’ll become better at detecting filler words. Here’s another example:

🛑 Don’t: The logging system performs the monitoring of application errors.

✅ Do: The logging system monitors application errors.

The table below suggests concise alternatives to common filler words.

Tip 3: Subordinate Clauses Should Support, Not Distract from, the Main Sentence Idea

Every sentence contains:

A main clause
Zero or more subordinate clauses

Subordinate clauses should enhance the main clause’s idea rather than introduce unrelated information. Here is a list of words that commonly introduce subordinate clauses: which, that, because, whose, until, unless, and since.

Your goal is to use subordinate clauses that support the main idea without branching off into a separate concept.

Let’s look at examples where subordinate clauses distract from the main idea, along with improved versions:

🛑 Don’t: Docker containers provide application isolation, which was first released as an open-source project in 2013 and has revolutionized deployment practices.

✅ Revised: Docker containers provide application isolation. It was first released as an open-source project in 2013 and has revolutionized deployment practices.

🛑 Don’t: Git helps track code changes effectively, which requires developers to learn specific commands that can be complex for beginners who are transitioning from other version control systems.

✅ Revised: Git helps track code changes effectively. It requires developers to learn specific commands that can be complex for beginners who are transitioning from other version control systems

In the following examples, the subordinate clauses support the main idea, so it’s fine to keep them:

✅ Do: Developers should use environment variables that contain sensitive configuration data.

✅ Do: She didn’t attend the meeting because she had a prior commitment.

Now, take a look at another example and try to identify the subordinate clauses and whether they should be removed:

❓Example: The project deadline has been extended, which will allow more time for testing, because some team members were out sick.

Technical Folks Love Lists: Use Them Correctly!

There are three main types of lists:

Numbered lists: Use these when items are ordered, and rearranging them would change the meaning.
Bulleted lists: Use these when items are not ordered, so rearranging them won’t change the meaning.
Embedded lists: Avoid these in technical information, as they contain items stuffed within a sentence and can be hard to read.

Tip 4: Convert Long Sentences into Lists

Often, we don’t realize that a long technical sentence can be converted into a list for better readability.

🛑 Don’t: To log in, users must enter their username and password, followed by a two-factor authentication code that will be sent to their registered device, which they must then input within 60 seconds.

✅ Do: The login process requires:

Username
Password
Two-factor authentication code

When you see an “or” conjunction in a long sentence, break it down into a list.

🛑 Don’t: To secure your AWS account, you can enable multi-factor authentication, implement IP-based restrictions, rotate access keys regularly, or set up CloudWatch alerts for suspicious activities.

✅ Do: To secure your AWS account, you can: