Plain Language — Writing Clearly for Technical Documentation

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

Plain language is writing that readers can understand the first time they read it. It uses simple words, short sentences, and clear structure. Plain language does not mean dumbing down content. It means making content accessible to the widest possible audience.

In this lesson, you will learn how to write technical content using plain language principles without losing precision or technical accuracy.

What You'll Learn

You will understand plain language principles, replace jargon with clear alternatives, and write sentences that readers understand on first reading.

Why It Matters

Plain language improves comprehension for all readers including non-native speakers. It also improves translation quality and search engine ranking.

Real-World Use

DodaTech rewrote the DodaZIP installation guide using plain language. The average support ticket resolution time dropped from 8 minutes to 3 minutes because users understood the instructions immediately.

flowchart LR
  A[Complex Text] --> B[Plain Language]
  B --> C[Simple Words]
  B --> D[Short Sentences]
  B --> E[Clear Structure]
  C --> F[First-Time Understanding]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Plain Language Principles

Use the simplest word that conveys the correct meaning. Utilize becomes use, initiate becomes start, terminate becomes end. Shorter words are not always better, but they usually are.

Write short sentences. Each sentence should contain one idea. If a sentence has more than 20 words, consider breaking it into two.

Use active voice. The subject performs the action. Passive voice hides who does what and adds unnecessary words.

# Before
The installation of the software package should be performed by the user
prior to the initialization of the compression process.

# After
Install the software before compressing files.

# Before
The aforementioned configuration parameter is utilized for the purpose
of specifying the compression algorithm.

# After
The algorithm parameter selects the compression method.

Jargon and Technical Terms

Some jargon is necessary for precision. Define technical terms when they first appear. If you can use a common word instead of jargon, do so.

Create a glossary of terms used in your documentation. Link to glossary definitions on first use of each term.

Avoid acronyms without expanding them first. Write Network File System on first use, then NFS thereafter.

# Plain language in code documentation

# Bad: Too much jargon
# Initiate the compression pipeline by instantiating the Compressor class
# with the requisite algorithm parameter.

# Good: Plain language
# Create a compressor and choose the compression method.
from dodazip import Compressor

compressor = Compressor(algorithm="gzip", level=6)

Common Mistakes

1. Using Jargon for No Reason

Utilize when use works. Leverage when use works. Implementational when implementation works.

2. Long Noun Chains

Server-side client request validation pipeline becomes Pipeline for validating requests from clients on the server.

3. Double Negatives

Not uncommon when common works. Do not disable unless you mean enable.

4. Unnecessary Modifiers

Very unique, quite difficult, really important. Remove modifiers that add no meaning.

5. Passive Voice Habit

The file is compressed by the algorithm. Say The algorithm compresses the file.

6. Nominalizations

Make a decision becomes decide. Perform an analysis becomes analyze.

7. Long Paragraphs

One idea per paragraph. Three to five sentences max.

Practice Questions

1. What is plain language?

Writing that readers can understand the first time they read it. It uses simple words, short sentences, and clear structure.

2. What is wrong with the word utilize?

It is longer than use and means the same thing. Prefer shorter words.

3. How do you handle necessary jargon?

Define technical terms on first use. Link to a glossary for reference.

4. What is a nominalization and why should you avoid it?

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

5. Challenge: Take a technical paragraph with at least 100 words. Rewrite it using plain language principles. Count the word reduction and test the rewritten version on a colleague for comprehension.

FAQ

Mini Project

Take a page of technical documentation from any source. Rewrite every sentence using plain language principles. Count the original word count and the new word count. Show before and after to a colleague and ask which is clearer.

What's Next

Next: Active vs Passive Voice