Short Sentences
Introduction
People in the IT industry do not read documentation for pleasure. They are often busy and distracted, skimming for the information they need. Long sentences make it hard to quickly grasp key points, causing confusion and frustration. By keeping sentences short, you improve readability and ensure your message is understood.
Convert Long Sentences to Lists
When you see an embedded list of items or tasks within a long sentence, consider refactoring that sentence into a bulleted or numbered list. Lists are easier to scan and understand, especially in technical documentation.
Example
Avoid |
Preferred |
|---|---|
To configure ESP32 for Deep-sleep mode, you need to set the wake-up source, configure the GPIO pins, and enable the low-power mode in the firmware. |
To configure ESP32 for Deep-sleep mode:
|
To flash the firmware, you need to connect ESP32 to your computer, open the ESP-IDF command prompt, navigate to the project directory, and run the idf.py flash command. |
To flash the firmware:
|
Lists help readers quickly grasp key takeaways without getting lost in lengthy sentences.
Convert Long Sentences to Multiple Short Sentences
If a sentence is too long and cannot be converted into a list, split it into multiple short sentences. This approach improves readability and reduces cognitive load.
Example
Avoid |
Preferred |
|---|---|
ESP32-S3 supports Wi-Fi and Bluetooth connectivity, and it includes a dual-core processor that operates at up to 240 MHz, making it suitable for IoT and AI applications. |
|
The ESP-IDF framework provides a menuconfig tool that allows developers to configure project settings, such as enabling or disabling features, setting memory allocation parameters, and selecting the target hardware platform, all through an interactive interface. |
|
Short sentences make the information easier to process, especially when dealing with extensive technical details.
Eliminate or Reduce Extraneous Words
Remove unnecessary words to make sentences concise. Extraneous words add clutter and distract from the main message.
Example
Avoid |
Preferred |
|---|---|
In order to successfully complete the process of flashing firmware onto ESP32, you need to carefully follow all of the steps outlined in the user guide. |
To flash firmware onto ESP32, follow the steps in the user guide. |
It is important to note that the ESP-IDF framework includes a variety of tools that can be used to build, flash, and debug firmware for Espressif chips. |
The ESP-IDF framework includes tools to build, flash, and debug firmware for Espressif chips. |
By eliminating redundant words, the sentence becomes more direct and easier to read.
See Chapter Words for more tips on words.
Reduce Subordinate Clauses
A clause is an independent logical fragment of a sentence, which contains an actor and an action. Subordinate clauses modify the idea in the main clause, and make sentences unnecessarily complex. Reduce or eliminate them to simplify your writing.
Example
Avoid |
Preferred |
|---|---|
When using the ESP-IDF build system, which relies on CMake, you must ensure that the required toolchain is installed and that the environment variables are correctly configured before running the build commands. |
The ESP-IDF build system relies on CMake. Before running the build commands, ensure that the required toolchain is installed, and the environment variables are correctly configured. |
If ESP32 enters a reboot loop, which can occur due to a watchdog timer reset or insufficient power supply, you should check the power source and review the firmware logs for errors. |
ESP32 may enter a reboot loop due to a watchdog timer reset or insufficient power supply. Check the power source and review the firmware logs for errors. |
Simplifying subordinate clauses makes the sentence structure clearer and more direct.
Replace Complex Words with Simpler Words
Use simple words instead of complex or technical terms when possible. This is another efficient way to shorten sentences.
Example
Avoid |
Preferred |
|---|---|
Utilize the ESP-IDF configuration utility to ascertain the optimal parameters for wireless connectivity implementation. |
Use the ESP-IDF configuration utility to find the best parameters for wireless connectivity. |
The user must terminate the debugging session before initiating the firmware flashing process to avoid potential conflicts. |
The user must stop the debugging session before starting the firmware flashing process to avoid conflicts. |
Common word replacements are as follows:
Avoid |
Preferred |
|---|---|
Utilize, leverage |
Use |
Implement |
Set up, create |
Ascertain |
Find out, check |
Commence |
Start, begin |
Terminate |
End, stop |
Facilitate |
Help |
Optimal |
Best |
Functionality |
Feature |
See Chapter Words for more tips on words.