Clear Sentences

Introduction

Clear sentences are the foundation of effective technical documentation. They ensure that users can easily understand complex technical information without ambiguity. Writing clear sentences involves careful attention to sentence structure and the logical flow of ideas. To achieve this, use the guidelines in this chapter while keeping in mind that flexibility is crucial. Adapt these principles to suit the document’s purpose, audience, and context.

Reduce May and May Not

The use of “may” and “may not” can introduce ambiguity into documentation. Instead, provide specific information to make your writing more precise.

Preferred	Avoid
The system resets if power is interrupted for more than 10 ms.	The system may reset when power is interrupted.
The module fails to initialize if the input voltage fluctuates beyond 5%.	The module may fail to initialize if the input voltage is unstable.
Operational stability depends on preventing a voltage drop, which occurs if the load current exceeds the specified threshold.	A voltage drop may occur if the load current exceeds the specified threshold, which is critical for operational stability.

Reduce There is/There are

“There is” and “there are” often add unnecessary words and weaken the sentence structure. Replace them with more direct expressions.

Preferred	Avoid
A signal indicates the power-on state.	There is a signal that indicates the power-on state.
Several registers configure GPIO settings.	There are several registers used for GPIO configuration.

Use Parallel Structure

Maintain consistent grammar in lists or comparisons.

Preferred	Avoid
The system monitors temperature, current, and voltage.	The system monitors temperature, current, and is checking voltage.

Focus

Ensure each sentence conveys one primary idea. Avoid cramming multiple unrelated ideas into a single sentence.

Preferred	Avoid
The chip operates at low power, making it ideal for battery-powered applications. It features a high-speed ADC for precise and fast signal processing. Multiple communication protocols enhance its versatility.	The chip operates at low power, features a high-speed ADC, and supports multiple communication protocols to enhance its versatility.
The signal propagation delay is 5 ns. The input setup time is 3 ns. Both timing requirements must be met for reliable operation.	The signal propagation delay is 5 ns, and the input setup time is 3 ns, both of which must be met for reliable operation.

Contrast and Emphasis

Highlight key differences or important details by structuring sentences to emphasize contrasts.

Preferred	Avoid
While idle mode ensures low power consumption, normal operation consumes significantly more energy.	The chip supports low power consumption during idle, but normal operation consumes more energy.
Although the new firmware version includes enhancements, it removes some features from the previous version.	The new firmware version includes enhancements, but some features from the previous version are removed.

Provide feedback about this document