Simplified Technical English Rewrite

Simplified Technical English rewrite

Rewrite the source paragraph in Simplified Technical English. Preserve the source meaning exactly.

Meaning

• Keep every fact, number, condition, warning, limitation, instruction, action, result, cause, and effect.
• Keep the original actor. Do not change who performs an action.
• Keep timing, order, scope, degree, uncertainty, and relationships between events.
• Keep each condition with the action or result that depends on the condition.
• Keep each stated cause connected to its result.
• Keep exact values exact and approximate values approximate.
• Do not add facts, explanations, reasons, choices, advice, or recommendations.
• Do not change a requirement, permission, possibility, warning, or prohibition.
• Keep the original order when order affects the result.

Sentences

• Write no more than 20 words in each sentence.
• Use one main action, condition, or result in each sentence.
• Split long sentences at natural points.
• Repeat the actor or condition when repetition keeps the meaning clear.
• Use active voice when the source identifies the actor.
• Do not address the reader directly. Name the reader, user, operator, administrator, or system.
• Use “must” for a required action.
• Use “can” for permission or ability.
• Use “cannot” for a prohibition or impossibility.
• Preserve possibility and uncertainty with wording such as “is possible”.
• Do not use “should”, “might”, or “may” unless the source has the same meaning.
• Do not turn a conditional action into a general requirement.

Words and terms

• Use common words, direct grammar, and simple verbs.
• Use one technical term for one thing throughout the rewrite.
• Prefer “use”, “get”, “run”, and “do” when they keep the source meaning.
• Do not use “perform” or “additional”.
• Do not use informal shortened words. Write “application”, not “app”.
• Expand ordinary abbreviations in prose. Write “application programming interface”, “uniform resource locator”, “Coordinated Universal Time”, “repository”, “configuration”, “and so on”, and “ante meridiem” when those meanings apply.
• Keep commands, code names, variable names, header names, file names, paths, quoted values, placeholders, and other exact values unchanged.
• Keep numbers, units, symbols, and capitalization unchanged unless the source gives an expanded form.
• Do not replace an exact value with an approximate expression.
• Do not replace an approximate expression with an exact expression.
• Preserve words that show degree, uncertainty, or limitation.

Final check

Compare the rewrite with the source.

• Check every fact, number, condition, warning, limitation, instruction, action, result, cause, and effect.
• Check every actor, degree, uncertainty, timing, order, and scope.
• Check that conditional actions remain conditional.
• Check that causes remain connected to their results.
• Count the words in every sentence. Split every sentence longer than 20 words.
• Check that ordinary abbreviations are expanded.
• Check that “perform” and “additional” do not appear.
• Check that each technical term has one meaning throughout.
• Check that no new information appears.

Examples

Source: “If the token expires or an administrator revokes it, the user must run the login command again to get a new token.”

Rewrite: “If the token expires, the user must run the login command again. The user gets a new token. The same rule applies if an administrator revokes the token.”

Source: “Configuration files load in this order: the global configuration in /etc, the user configuration in the user home directory, and the project configuration in the repository root.”

Rewrite: “Configuration files load in this order. First, the global configuration in /etc loads. Next, the user configuration loads. Last, the project configuration loads.”

Source: “If the build fails with an out-of-memory error, the user can try to increase the maximum heap size of the Java virtual machine through the JAVA_OPTS environment variable.”

Rewrite: “If an out-of-memory error stops the build, the user can try to increase the Java Virtual Machine maximum heap size. The user can use JAVA_OPTS.”

Source: “The export feature is very slow because it performs separate queries for each record.”

Rewrite: “The export feature has a very long run time. Separate queries for each record cause the long run time.”

Source: “The translator must translate each value and leave the keys unchanged because the application uses the keys to find each string.”

Rewrite: “The translator must translate each value. The translator must leave the keys unchanged. The application uses the keys to find each string.”

Source: “Other engineers need to inspect a server or grant temporary access for a maximum of 4 hours.”

Rewrite: “Other engineers need to inspect a server or grant temporary access. Temporary access has a maximum duration of 4 hours.”