209. Accuracy and the editing pass¶
Remove only from a sentence and the rhythm may improve. The promise may also become larger than the product. Small edits deserve attention because they can change meaning without looking like changes to the subject at all.
An editorial pass should leave the page accurate, usable and recognizably written by someone attending to the material. These qualities need different checks. Fluency does not establish behavior, and a correct list of facts does not yet make an explanation. The finished page needs both.
Establish what the page claims to describe¶
Identify the product, version, platform, audience and task. Add mode, configuration or edition when it affects the result. A claim can be true in one of these contexts and wrong in another without either source being dishonest.
A current help page and a historical release note also have different jobs. Updating maintained guidance does not justify replacing an old release's behavior with the current one.
Choose evidence suited to the claim. A specification can establish a documented contract. An observed run establishes what happened under its conditions. Source code can explain a reachable implementation; the mere presence of a function does not prove that users encounter it. A support report can establish a reported problem without establishing its frequency or cause.
For an interface instruction, verify the label, location, state and action. For shortcuts, account for platform, focus and relevant customization. For API examples, inspect the applicable documentation and test the intended operation in an appropriate environment.
Keep a private note sufficient to assess or reproduce the check: claim, source, conditions, result and limit. The record can be small. It must be real.
Public citations belong where they help readers assess or follow a claim. Internal review records remain private, and a published instruction need not carry the entire history of how its wording was established.
Resolve disagreement at the level of the claim¶
When two sources differ, compare their versions, platforms, starting states and operations. A changed default can explain different observations. A renamed control can explain different strings. Record the distinction before choosing a sentence.
A newer date is useful context, not proof. A more restrictive claim is not automatically more accurate. If available evidence cannot settle the issue, identify the check or product knowledge that could.
Keep uncertainty visible in the working material. Before publication, resolve the question, narrow the claim to what is established, or remove it. Do not replace a missing route with one remembered from another application.
For a fictional verification record, suppose one export succeeded with one supplied file in one version. The supported statement is that this run succeeded. “Export always succeeds” does not follow, and “export usually succeeds” invents a frequency that was not measured.
The bounded observation may belong in the review record rather than the public help. A page that needs a broader contract requires evidence for that contract. Good wording cannot promote a single run into a specification.
Compare meanings before comparing elegance¶
Read the source and revision for actor, action, object, condition, timing, quantity, certainty and scope. These are the places where a fluent rewrite can quietly become a different account.
| Source distinction | Risk in a smoother revision |
|---|---|
| Enables an operation | Claims the operation has been performed |
| While a panel remains open | Describes a one-time action when it opens |
| May fail under a condition | Predicts certain failure |
| One tested version | Promises support across versions |
| Output in a supported format | Guarantees compatibility with every receiving application |
| An observed sequence | Assigns a cause that was not established |
A qualification is not expendable because it interrupts the rhythm. Move it, split the sentence or develop the explanation so the relationship stays clear. If a factual correction is needed, identify that correction separately from the style edit.
Exact labels, commands, identifiers and quotations have an additional constraint: the wording itself may be the fact. Improve the surrounding prose without silently improving those strings.
Give examples the same scrutiny as claims¶
A before-and-after example teaches two things: the stated writing lesson and whatever product behavior the reader infers from it. Check both.
Supply fictional facts before an invented rewrite. Identify hypothetical workflows and composites. Do not attach a plausible control or recovery action to a real product merely because it makes the example easier to finish.
A vivid scene may need a person, a decision and an object. In a real account, those details require evidence. A measured saving, customer reaction or quotation cannot be added as texture.
Preserve the problem the example is meant to teach. If the weak version is vague, the revision should clarify the supplied facts. It should not win the comparison by adding an unsupported feature, result or guarantee that the weak version never had available.
Check the reader's route¶
Read the page as an answer to its intended question. Can the reader find the relevant material, understand its conditions and reach a supported next step? A page made entirely of true sentences can still leave one of those jobs undone.
Place prerequisites before dependent actions and warnings before the choices they govern. Keep short explanations where they make an action intelligible. Link substantial background when leaving the task is a useful choice rather than a forced detour.
A reference needs local lookup. A procedure needs sequence and confirmation. An overview needs orientation and routes. Choose the structure that serves the page instead of forcing all three into the same shape.
Cut repetition and material that answers another page's question. Retain a true qualification even when it makes the sentence longer. Length is a clue to inspect, not a score that declares the shorter version better.
Review what gives the prose its character¶
After the factual and structural checks, read for attention and movement. What can the reader picture? Which relationship develops across the paragraph? Where does the thought change direction or reach its consequence?
Preserve a concrete detail that explains the situation. Let a longer sentence carry a useful connection. Use a short sentence when it marks a real turn. Do not replace every distinctive phrase with the smallest neutral equivalent.
An analogy should clarify one relationship without importing extra behavior. An aside should answer a likely question or reveal a relevant discrepancy. A dry observation can let the reader notice the difference between a promise and its result. Keep these choices when they help the page do its work.
Then remove the expressive layer in your mind and check the literal account. The facts and necessary instructions must still hold. Restore the useful style after that check; a fact audit is not an instruction to leave the prose bare.
For an edit of supplied writing, preserve effective perspective, uncertainty and voice within the requested depth. Do not give a cautious author confidence they did not express or add an anecdote they did not experience.
Diagnose the actual defect¶
Vague praise, repetitive transitions, unsupported assurances and mechanically matched sentences are editing problems. They do not establish who or what wrote the text.
Describe what fails: an unnamed actor, a missing condition, an interchangeable example, a repeated point, or a conclusion without evidence. Repair that defect instead of trying to make the paragraph look as though it came from a particular kind of author.
Search tools can locate suspected patterns. Read each hit in context. A real comparison may need contrast, an exact technical term may resemble a fashionable word, and a historical quotation may legitimately contain an old name.
Check names, units, punctuation, capitalization, links, code and labels. Inspect non-Latin text for its actual meaning and role; its script is not an error. Look for unresolved placeholders, duplicated paragraphs, broken markup and instructions to an editor that escaped into the publication.
Review how people are described. Avoid contempt, blame and invented motives. Do not assign a disability, emotional state or level of competence merely to make an example seem considerate. Write the task and observed difficulty clearly.
Ask for review that can answer the remaining question¶
A product expert can check behavior. An editor can inspect explanation and consistency. An intended reader can reveal a missing assumption or unclear route. One person may cover several roles; choose coverage according to the change and its consequences.
Give reviewers the purpose, relevant evidence, changed claims and unresolved questions. Ask for the passage, the problem and its effect. Distinguish a factual error from a preference so that disagreement can be resolved on the right basis.
For task instructions, observe a suitable reader working from the stated conditions. Record hesitation, misinterpretation and missing information. One attempt is useful evidence about that attempt. Do not manufacture exhaustion or hostility as a required persona, and do not generalize one response to all readers.
Prioritize defects by consequence. A wrong command, hidden condition or unsupported guarantee can prevent publication even when the page has excellent punctuation. Track permissible remaining work explicitly. A checked box does not remove the problem it describes.
Inspect both source and output¶
Automated checks can establish properties such as syntax, file presence, link or anchor validity, protected terminology, publication boundaries and exact fixture content. Use them for those jobs and inspect their failures.
Do not weaken a meaningful check merely to obtain a passing result. Conversely, when a check is too broad, repair its contract and verify the intended cases. The objective is a useful safeguard, not unquestioning loyalty to a script.
Inspect the generated page for headings, tables, lists, code, images, notes, navigation and copied text. Correct source can render badly. An attractive screenshot can omit a paragraph or conceal a broken interaction.
When headings move or disappear, check incoming links and preserve useful anchors or update their callers. A link that resolves to an unrelated section has not been repaired by avoiding a 404.
After a correction, rerun the affected checks. Broaden verification when the change or failure warrants it. Report what the evidence establishes: a build and link check do not certify every product claim, translation or reader outcome.
Worked review: preserve a time boundary¶
Use this fictional packet:
- A comparison view updates while Live preview is on.
- Turning the setting off leaves the last displayed comparison visible.
- No saved-file behavior is supplied.
Draft:
Live preview seamlessly keeps your work up to date, even when you turn it off.
Factual revision:
The comparison view updates while Live preview is on. Turning it off leaves the last displayed comparison visible.
Style revision:
While Live preview is on, the comparison view follows the updates. Turn it off, and the last comparison stays on screen. A visible result is not necessarily a current one.
The final observation develops the distinction between visibility and continued updating. It does not assert what happened to the saved file. The example's personality comes from noticing that distinction, not from adding a joke or an unsupported promise.
For the second pass, remove the fact about what remains visible after the setting is turned off. The second and third sentences can no longer be carried forward as though nothing changed. Revise from the reduced packet, then decide whether a different expressive ending still helps.
Then compare the two revisions aloud. Identify where each sentence changes the reader's understanding. Keep the longer setup if it holds the condition clearly; keep the short final observation only while its conclusion remains supported. This is the second pass doing two jobs together: checking the claim and judging the way the prose arrives at it.
Keep the review useful to the next editor¶
When behavior, labels, prices, support or policy change, inspect the related instructions, examples, captions and summaries. Update current guidance while preserving the scope of historical records.
Record the change, evidence, checks and remaining limits where the project expects them. Keep internal targets and review history out of general writing advice. Preserve attribution where it belongs without filling public prose with private process notes.
A checklist helps expose omissions. Revise it when recurring errors show a gap, and remove checks that no longer serve the work. Its purpose is a page that can be trusted and used, not a record that grows more impressive each time it is copied.
Checklist¶
- The page's purpose, audience and applicable product conditions are clear.
- Claims have suitable evidence and conflicts remain distinguishable from errors.
- Rewrites preserve actors, conditions, timing, quantities, certainty and scope.
- Examples teach the intended lesson without inventing proof.
- Structure supports the reader's actual route.
- A style pass preserves useful detail, viewpoint, rhythm and relationships.
- Pattern searches lead to contextual diagnosis rather than authorship claims.
- Review covers the remaining factual, editorial and usability questions.
- Source and generated output have been checked at the scope claimed.
- The record names actual results and material limits.