Review 3.8: the Word add-in rebuilt on the native comments API

Review 3.8 is a rebuild of the Word add-in. Users will notice that flags now appear as ordinary Word comments and that proposed redlines are ordinary tracked changes. Underneath, almost everything about how the add-in talks to Word has changed. This note is for the people who will have to support it.

What changed

• Flags are native Word comments. Each flag is a comment anchored to the clause text, authored as “ZAAN Review”, carrying the severity, the playbook rule and the explanation. Comments can be replied to, resolved and deleted using Word’s own controls, and they travel with the document.
• Proposed redlines are native tracked changes. Accepting a redline is Word’s accept-change. Rejecting it is Word’s reject-change. There is no separate ZAAN accept button, though the pane still lists all proposals and lets you jump between them.
• The side pane is now an index, not a store. It lists flags and redlines by reading them back from the document. Close the pane, reopen it, open the document on another machine: the state is in the file.
• Offline-safe. Because the state lives in the document, a review completed on a train survives. Flags are generated server-side, but once written they need no connection.
• Document fidelity. We no longer touch the document’s XML directly. All writes go through the Office JavaScript API. Numbering, styles, fields and content controls are left as Word leaves them.

Why we rebuilt it

The previous add-in, from Review 3.0 to 3.6, drew its own annotations over the document and kept the review state in our pane. It let us ship features quickly and gave us full control over the look. It also caused the three support categories that, between them, accounted for just over half of all add-in tickets in 2024.

State loss. If the pane crashed, closed unexpectedly or lost its session, in-progress accept and reject decisions were gone. We added recovery, then more recovery. It was never good enough, because the real problem was that the document and the review had become two different things.

Collaboration. A partner opening a document that an associate had reviewed could not see the associate’s decisions unless they also opened the pane, signed in and loaded the same session. Comments made in Word and flags made in ZAAN lived in different places. Firms wanted one conversation on the document; we were giving them two.

Fidelity. Writing redlines into the document ourselves meant we were responsible for every edge case in Word’s document model. Multi-level lists, legacy fields, documents converted from other formats, content controls from third-party tools. Each one eventually produced a ticket of the form “ZAAN broke my numbering”. Usually we had. Sometimes we had merely exposed something fragile, but the distinction did not help the user.

Putting the state in the document, through the APIs Word provides for exactly this purpose, removes all three categories at root. It also means a document reviewed in ZAAN looks like a document reviewed by a colleague, which is what it should look like.

What it costs

We want to be plain about the trade-offs.

Minimum versions. The native comments API with the features we rely on requires Microsoft 365 current channel or the semi-annual channel from the second half of 2024, on Windows and Mac, or Word on the web. Perpetual-licence Word 2019 and 2021 are not supported in 3.8. Firms on those versions can remain on 3.6, which we will maintain with security fixes until at least the end of 2025, but will not receive new review features.

Rendering. Word’s comment pane is Word’s. Severity is shown as a prefix in the comment text (“[High]”) rather than as a coloured marker, because the API does not let us colour comments. The side pane retains colour and filtering. Some users will find this a step backwards visually. We think the collaboration gains outweigh it.

Performance on very large documents. Writing several hundred comments through the API is slower than our previous direct write. A 120-page agreement with 140 flags takes around nine seconds to annotate on a typical laptop, up from about three. Flags appear progressively, so the first ones are visible almost immediately. We are working on batching.

What to check after upgrading

1. Confirm the Word channel and build across the estate. The add-in displays a clear message and declines to load on unsupported builds, but it is better to know beforehand.
2. Open a previously reviewed document. Flags from 3.6 sessions will not be present as comments; the 3.6 state was never in the file. Re-running the review regenerates them. Decisions made in 3.6 are not carried over.
3. Check document templates that use content controls or legacy fields. These were the main source of fidelity problems before and are now untouched; verify nothing else in your workflow depended on the old behaviour.
4. Brief users that accept and reject are now Word’s own buttons. Most find this obvious. A few looked for the ZAAN button for a day.

Known limitations

• Word on the web does not yet support all comment-threading operations. Replies work; resolving a thread from the ZAAN pane does not, though it works from Word’s own interface.
• Documents with existing tracked changes from the counterparty will show ZAAN’s proposals interleaved. The pane can filter to ZAAN-authored changes only; Word’s own review pane cannot.
• The add-in cannot yet annotate text inside footnotes, text boxes or headers. Flags for those regions are listed in the pane with a document position but no anchored comment.

Smaller changes in 3.8

• The pane remembers filter settings per user, per practice group.
• Keyboard navigation between flags (Alt+N / Alt+P on Windows, Option on Mac).
• Export of the flag list to a spreadsheet, including resolution state.

The review is now in the document. That is where it should have been from the start.