> ## Documentation Index
> Fetch the complete documentation index at: https://lib.findy.co.jp/llms.txt
> Use this file to discover all available pages before exploring further.

# How to edit technical articles: roles and term checks

> Defines the three roles of technical editing, how to check technical terms against a term list, and the order in which to edit a draft.

## Overview

Technical editing is the work of taking a draft written by an engineer and
making it accurate, readable, and consistent before it is published in a
technical media outlet such as a company engineering blog or an interview
series.

This page covers what that editing is responsible for, how to check
technical terms, and the order in which to work through a draft.

## What technical editing is

### Three roles

Technical editing has three roles. Each one protects a different thing, so
a draft can pass one and still fail another.

| Role | What it protects | Typical question |
| - | - | - |
| Accuracy | The reader's trust in the content | Is this claim true for the version and conditions the article describes? |
| Readability | The reader's time | Can a reader in the target audience follow the argument without rereading? |
| Consistency | The outlet's credibility as a whole | Is the same thing named the same way here as in every other article? |

Accuracy comes first because an error in a technical article costs more than
an awkward sentence. A reader who follows an incorrect step loses time, and
a reader who notices the error stops trusting the rest of the article.

Readability is judged against the target reader, not the editor. An editor
who already knows the topic will fill gaps without noticing them, so the
check is whether the text works for someone who does not.

Consistency matters at the level of the outlet rather than the single
article. When each article spells the same product or concept differently,
readers start to doubt whether the outlet checks anything at all.

## Checking technical terms

### What to check

Term checks catch errors that a general proofreading pass misses, because
a misspelled product name or an outdated version number reads as perfectly
fluent text.

| Check | What goes wrong | What to do |
| - | - | - |
| Spelling variants | The same thing is written several ways in one article | Pick one form and use it throughout |
| Abbreviations | An abbreviation appears before the reader knows what it stands for | Spell it out on first use, or avoid it if the audience may not know it |
| Proper nouns | A product or project name has the wrong capitalization or spacing | Use the official spelling from the product's own documentation |
| Version and time dependence | A statement is true only for a certain version or at the time of writing | State the version or date the statement applies to |

Version and time dependence needs the most attention. A statement such as
"this option is the default" may be true when written and false a year
later, so the article should say which version it was verified against.

### Examples to avoid and recommend

| Avoid | Recommend | Reason |
| - | - | - |
| Javascript, javascript | JavaScript | Official capitalization |
| Github, github | GitHub | Official capitalization in body text |
| Postgres and PostgreSQL mixed in one article | PostgreSQL throughout | One name per thing within an article |
| front end, front-end, frontend mixed | One form, used throughout (for example, "frontend") | Spelling variants of a common noun |
| K8s on first mention | Kubernetes, with "K8s" only after it is introduced, if at all | Abbreviation before definition |
| "the latest version supports this" | "Version 3.2 supports this" | Time-dependent wording |

### Keep a term list

Checking terms from memory is unreliable, because each editor remembers a
different set of rules. A term list fixes the rules in one place and turns
the check into a comparison.

A practical term list has three columns: the correct form, examples of
incorrect forms, and a note explaining the rule or its source. The note
matters because it lets the next editor decide edge cases instead of
guessing.

> [!TIP]
>
> Check only against the list. Do not "correct" terms that are not in it
> based on intuition, because a confident guess about an unfamiliar name
> introduces new errors. When a new term keeps causing variation, add it to
> the list with its source.

## The editing process

Edit a draft in order from the largest unit to the smallest. Fixing wording
in a paragraph that later gets cut wastes the work, so structure comes
before sentences.

**1. Check the structure**

Confirm the target reader. Check that the headline
promises what the article delivers, and that the sections follow an
order the reader can follow.

**2. Check the facts**

Verify each claim that can be wrong: definitions, classifications,
numbers, version-dependent behavior, and comparisons. Accept as evidence
only primary sources such as official documentation or specifications.
When a claim cannot be verified, ask the author for the source rather
than rewriting it.

**3. Check the terms**

Compare the terms in the draft against the term list. Unify spelling
variants, expand abbreviations on first use, and confirm that proper
nouns and version references are correct.

**4. Adjust the wording**

Shorten long sentences, remove redundant phrasing, and replace jargon
the target reader may not know. Keep each change small and explainable.

**5. Confirm with the author**

Send the edited draft back with the reason for each substantive change.
The author approves the final version before it is published.

Generative AI can help prepare a draft before this process starts, for
example by producing a first outline or listing candidate headlines from a
set of requirements. Its output is a starting point that still goes through
every step above, especially the fact check.

## Caveats

### Respect the author's intent

The article belongs to its author. An editor's change is justified when it
serves accuracy, readability, or consistency; a change made only because the
editor would have phrased it differently is not.

When a passage is unclear, ask what the author meant before rewriting it. A
rewrite based on a wrong guess can change the technical meaning while
sounding more polished, which is worse than the original.

### Avoid over-editing

Over-editing removes the author's voice and makes every article in the
outlet sound alike. It also slows the process, because the author has to
review changes that were never necessary.

Limit each edit to the problem it fixes. When an error is found, correct
that passage only, and leave the surrounding text and the author's style as
they are.

> [!NOTE]
>
> Separate required changes from suggestions when returning a draft.
> Required changes are errors in fact, terms, or the outlet's standards;
> suggestions are improvements the author may accept or decline. Marking the
> difference keeps the author's decisions in the author's hands.

## Related pages

> [card] [The role of DevRel](https://lib.findy.co.jp/devrel/engineering-culture.md)
>
> Where technical media fits among the ways a company takes part in the
> engineering community.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.