Sentence diagnostics that stay where the sentence is

Read the draft or read the findings

A side panel forces a choice that no reviewer wants to make: look at the text, or look at the analysis. In practice it means reading a sentence, moving your eyes right, finding the matching item, moving back, and losing the thread of a paragraph in the process.

A tooltip removes the choice. The text stays at full measure with one underline per problem, and the explanation appears where you are already looking and leaves when you are done. The document keeps its shape, which is what makes it readable in the first place.

The interesting engineering problem is collision. A tooltip near the top of the viewport has to flip below its anchor; one near an edge has to shift inside. Get that wrong and the diagnostic that explains a problem is clipped by the same window that is showing it, which is worse than a panel because it looks like a bug in the text.

Keyboard access matters for the same reason. If focus opens the diagnostic, then tabbing through a document becomes a review pass — and a screen-reader user gets the same information as a mouse user, which is not true of hover-only designs.

Four checks worth interrupting a read

Passive constructions with no actor are the first, because they hide responsibility. Mistakes were made is a sentence with no subject, and in a technical or legal document that absence is usually deliberate. Flagging it does not mean rewriting every passive; it means deciding who did the thing.

Sentence length past thirty words is the second. Long sentences are not wrong, but they cost the reader, and a draft with twelve of them in a row has a rhythm problem rather than twelve separate problems.

Stacked hedges are the third. Two qualifiers in one sentence usually cancel each other out: possibly may suggests the writer has no view at all. One hedge, well chosen, is accuracy; three is abdication.

Robotic openers are the fourth, and they are aggregated in the panel as a share of every sentence so that a single flagged paragraph does not get presented as a pattern when it is not one.

• Passive with no actor: decide who is responsible.
• Over thirty words: split it, or cut a clause.
• Two or more hedges: pick one, or commit.
• Robotic opener: delete it and start on the subject.

Burstiness is a rhythm measure, not a verdict

Burstiness compares sentence length variation against the mean. Very flat prose scores low and tends to read as machine-generated, because models produce sentences of similar length with similar internal structure. Humans are messier: a long explanatory sentence, then three words that land.

The caveat is important. Plenty of competent technical writing is flat on purpose, because procedures benefit from uniform sentence length and complex clauses resist being shortened. A low score is a hint about rhythm, not an accusation about authorship.

The useful response is variation where the argument allows it. When a paragraph makes two points, one of them usually deserves a short sentence. When a paragraph is a single procedure step, leave it alone.

Reading the piece aloud does most of this work for free, and it catches a different set of problems: the sentence you run out of breath in is a sentence that needs splitting, whatever the counter said.

Read a document by tabbing once

Because the diagnostic opens on focus as well as on hover, tabbing through the draft becomes a review mode. Each tab moves to the next marked sentence and each diagnostic appears without the pointer moving, which makes the pass faster than hovering and much faster than scrolling a side panel.

The same behaviour is the accessibility property of the design. A hover-only diagnostic is invisible to anybody who navigates with a keyboard or a screen reader, and a review tool that only works with a mouse excludes the people most likely to be doing careful editorial work in a text-only environment.

There is a third benefit that is easy to miss: tabbing forces a linear read. Hovering lets you jump to whatever looks interesting, which is how reviewers end up inspecting the sentences they enjoy fixing and skipping the ones in the middle of a dense paragraph.

If a diagnostic does not open on focus, that is a bug worth reporting rather than a limitation to work around, because it means part of the document cannot be reviewed at all by a keyboard user.

Passive voice and the question of who did it

A passive construction is not wrong. It is wrong when it hides an actor that the sentence needs: mistakes were made, the data was processed, the decision was taken. Each of those describes an event without a person, and in a technical, legal or corporate document that absence is usually a choice somebody made.

The diagnostic flags passives without an actor rather than passives as a class, which is the difference between a useful check and a rule that produces a hundred findings. The data was ingested by the scheduler names its actor and needs no attention. The data was ingested is a sentence that leaves a reader asking by what.

Rewriting is not always the answer. When the actor is genuinely unknown, or when naming them would be inaccurate, the passive is the honest construction. The finding is not delete the passive; it is decide whether the missing actor is a fact or a habit.

In incident write-ups this distinction carries weight, because the prose is read later as a record of who was responsible. A paragraph of actorless sentences reads as an effort to avoid saying, and readers notice even when they cannot point at the reason.

Hedging, and the sentences that need one

Hedges are not a defect. May, suggests, in some cases and according to are how an honest writer describes uncertain evidence, and a draft with none of them is usually a draft that has claimed more than it knows.

The defect is stacking: possibly may, it could be argued that perhaps, which cancels the claim rather than qualifying it. A sentence with two hedges asks the reader to hold two uncertainties at once and gives them no way to weigh either.

The repair is to pick the one that is true. If the evidence is limited, say limited. If the result is conditional, name the condition. A specific qualifier is more useful than a general hedge and it reads as confidence rather than as evasion.

So the diagnostic is best read as a question about whether you know, rather than as an instruction to sound certain. Certainty is easy to write and expensive to defend.

The diagnostics a tool will never show you

No mark will tell you that a sentence is boring, that a paragraph repeats the one above it, or that the piece makes the same point three times in different vocabulary. Those are the most common weaknesses in generated prose and none of them has a lexical signature.

They are visible in one place: the outline. Write down what each paragraph says in six words, then read the list. If two entries say the same thing, one of them is redundant, and that finding is worth more than any number of flagged adjectives.

The same trick catches the draft that has no argument. Ten paragraphs that each describe an aspect of the topic, with nothing building on anything, produce an outline of ten parallel entries. A reader feels that as a list even when the prose is fluent.

So the tool covers the sentence, the outline covers the piece, and a reviewer covers whether the whole thing is worth publishing. Three scales, three separate checks, and doing only the middle one is what most reviews actually consist of.

What a diagnostics pass leaves out

It has no view on truth. A sentence can be short, active, unhedged and completely false, which is the shape most confident misinformation takes. Accuracy lives in the claim tools and in the source comparison.

It cannot see structure above the sentence. A document can score beautifully line by line and still have no argument, because every sentence is fine and the sequence of them makes no point.

And it cannot be exported as a list, by design. This is a reading tool: the marks sit on the sentences and the value is in reading with them in view. When you need a report you can save, send or attach to a deliverable, that is the console, which produces findings a second person can act on without having been in the room.