Technical copyedit
Clarity and unambiguity beat every style rule. A technical text is read by someone with general technical knowledge and no knowledge of the project, who cannot ask the author. A copyedit removes everything that makes that reader stumble, guess or misread, and changes nothing the author meant.
Method follows H. Hering, How to Write Technical and Scientific Reports (3rd ed., Springer 2025), Sects. 2.6, 3.6–3.8.
Set up
- Rules. Look for the venue's style guide and the project's style sheet (
style-sheet.adocor similar). They override the defaults here. If there is no style sheet, build one while editing (see Output). - Level of edit. Match the request; if unclear, use medium and say so.
- light ("proofread", "check for typos", "just fix mistakes", "don't rewrite"): fix errors only: spelling, grammar, punctuation, notation (number–unit spacing, "Fig. 4"). Anything that is a matter of style or consistency rather than an error (unifying two terms, unit repetition in ranges, a better preposition) goes into a short "optional suggestions" list instead of the text. The author asked for their text back with the mistakes gone, not for an improved version.
- medium (default; "copyedit", "polish", "tighten"): light + sentence-level clarity: split overlong sentences, fix unclear references, replace vague words, unify terms, remove filler.
- heavy ("rewrite for clarity", "line-edit"): medium + reorder sentences within paragraphs, merge or split paragraphs, add introductory and connecting sentences.
- Keep the author's conventions where they are consistent and acceptable: language variety (British/American), voice (impersonal/passive or active "we"), citation style, one-sentence-per-line source layout. Change a convention only if the style sheet or the user says so.
Passes
Work in this order; each pass makes the next one easier.
1. Survey (no edits yet)
Read the whole text (all included files) once and collect:
- Terms: every name for each part, process, quantity and variant. Variants for one thing ("test rig / test bench / setup") must become one term. Choose the term from the style sheet; otherwise the most precise one that names the function ("retaining plate", not "plate"). Ask only when the choice would change the meaning.
- Abbreviations: where each is first used and whether it is defined there.
- Notation: units, number formats, symbols, hyphenation and capitalization variants.
2. Sentences and paragraphs (medium and heavy)
Apply references/style-rules.md. The rules that matter most:
- At most about 25–30 words per sentence; one new fact per sentence; one main clause plus at most one or two subordinate clauses. Split long sentences and make the logical link explicit (because, therefore, if … then, however).
- Clear references: every "it", "this", "which" points unambiguously to one noun. "The current I flows through the resistance R, which is small" → "The current I flows through the resistance R. R is small."
- Vague qualifiers (rather complex, much more linear, very fast, relatively low, significant without statistics): use the number if the text has it elsewhere; otherwise insert an author query asking for it; delete the qualifier if it carries nothing.
- Nominalizations and filler: "perform an evaluation of" → "evaluate"; "due to the fact that" → "because"; "it should be noted that" → delete.
- Name things by function, never "the design", "the system", "variant 2" when a real name exists.
- Passive voice is fine in impersonal reports, but the actor must be clear: "the valve is closed" → "the valve is closed by the controller" when it matters who or what does it.
- No telegraphic style (dropped verbs and articles), no double negatives, no emotional or colloquial wording ("works really nicely").
- The first sentence under a heading must stand on its own, not continue the heading.
- Paragraphs: one topic, at most about six sentences, no strings of one-sentence paragraphs.
- Heavy edit only: add missing introductory sentences before figures, tables and lists and at section starts; add connecting sentences at section ends. At medium level, query them instead.
3. Words and notation
Apply references/typography.md and, for numbers, units and formulas, references/formulas-units.md: space between number and unit, italic quantity symbols, en dash or "to" for ranges (one of them), real minus sign, consistent decimal marker, abbreviation defined at first use, hyphenation of compound modifiers, capitalization of headings and captions, parallel list items, no space inside brackets or before punctuation.
4. Consistency sweep
For every decision in the style sheet, search the whole document (all files, captions, tables, figure labels where editable) for the rejected variants and fix them. Variation across chapters written at different times is the most common residual error.
Never
- Change technical meaning, values, units of measured data, or the strength of a claim ("may" → "will", "suggests" → "proves").
- Invent a number, source, or fact to replace a vague word. Query instead.
- Introduce synonyms for elegance.
- Edit inside code listings, literal blocks, math source, URLs, citation keys, anchor IDs or
\labels, attribute entries, include directives, LaTeX command names, environments, the preamble or PlantUML sources (except label text the user asked to unify, and then only the label strings). - Reflow or rewrap AsciiDoc or LaTeX source more than the edit requires; small diffs are easier to review.
- In LaTeX, keep the markup the project uses for notation (siunitx
\qty,\cref,\gls, ties~) and use it for your own fixes: "5mm" becomes\qty{5}{\milli\metre}if the document uses siunitx, otherwise5~mm.references/typography.mdlists the LaTeX forms.
Author queries
When only the author can resolve something (missing value, ambiguous meaning, two terms that may or may not be the same thing, a claim that seems unsupported), leave a query instead of guessing:
- In AsciiDoc files: a comment line directly above the paragraph:
// ###AQ: Which deviation did the old sensor have (max. %)? Needed to replace "much more linear". - In LaTeX files: the same as a
%comment:% ###AQ: Which deviation did the old sensor have (max. %)? - In pasted text: numbered markers [AQ1] in the text and the questions listed after it.
If the report-review skill is installed, its linter lists ### markers, so open queries cannot slip into the final version.
Output
Files in a repository: edit the files directly. Then report:
- What level of edit you applied and which conventions you kept.
- Changes grouped by type with rough counts (e.g. "split 14 long sentences; unified 'test rig' (was also 'test bench', 'setup'); defined 5 abbreviations at first use; fixed 22 number–unit spacings").
- Three to five representative before/after pairs, so the author sees the kind of change.
- All author queries with file:line. Keep copyedit queries (meaning, missing values, ambiguous terms) separate from things you noticed outside the copyedit's scope (structure, contradictions with other chapters, doubtful technical claims); list the latter briefly under "Noticed, not edited" so they are not lost but do not drown the queries.
- Style-sheet decisions: update
style-sheet.adocif it exists; otherwise show the decision list and offer to save it (template:references/style-sheet-template.adoc).
Pasted text: return the edited text first, then the same report (items 2–5) in compact form. If the user wants to approve changes first, give a table of Before | After | Why for the substantive edits instead of applying them.
Keep the report short. The author wants the edited text and the decisions, not a lecture on style.