Writing Concisely — Eliminating Wordiness in Technical Documentation

In this tutorial, you will learn about Writing Concisely. We cover key concepts, practical examples, and best practices to help you master this topic.

Writing concisely means using the fewest words necessary to convey your message clearly. Every word should earn its place. Concise writing respects the reader's time and makes documentation easier to scan and understand.

In this lesson, you will learn techniques for eliminating wordiness while maintaining precision and clarity.

What You'll Learn

You will identify and eliminate common sources of wordiness, write more concise sentences, and edit existing content for brevity without losing meaning.

Why It Matters

Concise writing is faster to read and easier to understand. Readers can find information quickly and move on. Wordy writing frustrates readers and wastes their time.

Real-World Use

DodaTech implemented a conciseness check in their Vale configuration. Average page word count dropped by 25 percent while maintaining all technical content. User satisfaction scores improved.

flowchart LR
  A[Wordy Text] --> B[Edit]
  B --> C[Remove Redundancy]
  B --> D[Use Strong Verbs]
  B --> E[Eliminate Fillers]
  C --> F[Concise Text]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Eliminating Wordiness

Remove redundant phrases. In order to becomes to. Due to the fact that becomes because. At this point in time becomes now.

Replace wordy phrases with single words. In the event that becomes if. For the purpose of becomes for. With regard to becomes about.

Use strong verbs instead of verb-noun combinations. Make a decision becomes decide. Perform an analysis becomes analyze. Take action becomes act.

# Before (wordy)
In order to compress a file, the user must first install the DodaZIP
package and then utilize the Compressor class for the purpose of
initiating the compression process.

# After (concise)
To compress a file, install DodaZIP and use the Compressor class.

# Before
Due to the fact that the file is extremely large, the compression
process may take a considerable amount of time.

# After
Because the file is large, compression may take several minutes.

Strong Verbs

Weak verbs like is, are, was, were often hide stronger verbs. The algorithm is capable of compressing becomes The algorithm compresses.

Use verbs that describe the specific action. The system makes use of becomes The system uses. The function provides the ability to becomes The function lets.

Avoid nominalizations where verbs become nouns. The implementation of the feature was done becomes The team implemented the feature.

# Concise code documentation

# Wordy
# The purpose of this function is to provide the ability for the user
# to compress files using the gzip algorithm that is built into the system.

# Concise
# Compress files using the built-in gzip algorithm.
def compress_with_gzip(input_path: str, output_path: str) -> int:
    """Compress a file using gzip. Returns the compressed size."""
    import gzip
    with open(input_path, "rb") as f_in:
        with gzip.open(output_path, "wb") as f_out:
            f_out.writelines(f_in)
    return Path(output_path).stat().st_size

Common Mistakes

1. Redundant Modifiers

Added bonus, end result, future plans, past history. The modifier repeats what the noun already implies.

2. Intensifiers

Very, really, extremely, quite. Remove intensifiers in most cases. The file is very large becomes The file is large.

3. Needless Prepositions

The field of compression becomes compression. The year of 2024 becomes 2024.

4. Wordy Transitions

In addition to that becomes also. As a matter of fact becomes in fact. At the same time becomes meanwhile.

5. Hedging

It might be possible that, it could be argued that, it seems that. State facts confidently unless they are truly uncertain.

6. Please and Thank You

Please install the software is fine for one instruction. Adding please before every command weakens the instruction.

7. Unnecessary Context

As you may already know, compression is a technique for reducing file size. If the reader already knows, skip it.

Practice Questions

1. What is the best way to make writing more concise?

Replace wordy phrases with single words, use strong verbs instead of verb-noun combinations, and remove redundant modifiers.

2. What is a nominalization?

A verb turned into a noun. Make a decision instead of decide. They add words without adding meaning.

3. How can you replace in order to?

Use to. In order to compress becomes to compress.

4. When is conciseness not appropriate?

When the context needs explanation. Do not remove necessary background or explanatory detail in pursuit of brevity.

5. Challenge: Take a 200-word documentation paragraph. Reduce it to 100 words while preserving all technical information. Count every word you removed and categorize the types of wordiness you eliminated.

FAQ

Mini Project

Take a 500-word section of technical documentation. Edit it for conciseness by removing wordy phrases, replacing weak verbs with strong ones, eliminating redundancies, and cutting intensifiers. Aim for a 30 percent reduction. Verify that all technical information is preserved.

What's Next

Next: Avoiding Ambiguity