Sending a document for review

Getting a document in front of somebody else, and handling what comes back.

A review is a round trip. You say things about passages, decide which of them somebody else should see, and send a copy out. It comes home with answers on it, and you work through the ones nobody has answered yet. Each step is a command, and this page covers them in order.

Saying who you are

Review ▸ Your Name… asks two things at once, on one sheet: the name to write, and whether to write one at all.

The name starts as the account this machine is logged in as, because more than one person often shares a machine, and the person reviewing a document is not always the one whose account it is. The application remembers the name for itself, not for one document.

The switch below it, write my name on marks and history, is a real option, not just a name field left blank. Turn it off and marks and history record what was done, not who did it. That matters when you are preparing a document for disclosure: a name is personal data, and it travels with the file to whoever receives it.

A name here is testimony, not proof. There are no accounts and no passwords: this is an application working on a file on your disk. What is written says only what the machine was told at the time, the same as a paper log book. That is unprovable, and it is still useful, for the same reason a log book is.

Saying something about a passage

Review ▸ New Comment (⌥⌘A) is the gesture every reviewer already has: pick out the words, say what is wrong with them.

A comment needs something under it. If you have text selected, in whichever pane you are working in, it is highlighted first and the comment hangs off that highlight; the highlight and the comment count as one undo step. If you have no words selected but a mark picked in a list, the comment goes on that mark instead. With neither, it tells you so.

With a row picked in the Changes list, it works differently: a comparison is worked out and then forgotten, so there is nothing to attach a comment to. Instead it adds a mark on the document under review, over the words as they now stand, and quotes the wording it replaced. That lets the reader make sense of it from one file, with no comparison of their own. A comment on a change is a question for somebody, so this one is shared the moment it is made: it lands in Talk, not in the marks list, and the status line says so.

A comment on an ordinary mark is different. You end up on the mark's card with the caret in the box, ready to type, and commenting does not put the mark up for review; a separate command does that, described below.

Review ▸ Edit the Comment… opens the words already on the mark in a window of their own, with write, split and preview modes, titled after the mark it is about. Only one such window opens at a time. The text is Markdown kept as plain text: nothing renders it inside the PDF, so a reader opening the file in another application sees exactly what was typed, not markup they cannot interpret.

Review ▸ Delete the Comment removes the words and leaves the mark in place. That is why it is a separate command: a highlight whose note turned out to be wrong is still a highlight. On a mark with nothing written on it, it says so and does nothing. Both actions are undoable.

The words live in the annotation's own contents field, the field meant for exactly this. A note written here is a note in Preview and Acrobat too, not something only this application can see.

Putting a mark up for review

Review ▸ Put a Mark Up for Review moves marks between Marks, which you keep to yourself, and Talk, which you have put up for an answer.

The menu item renames itself to say what it will do to the marks you have picked: Put This Mark Up for Review, Put These Marks Up for Review, Keep This Mark to Myself or Keep These Marks to Myself. One wording could not cover four different acts. When it is greyed out, it still names what it would do.

With several marks picked, the direction is decided once, by the first mark, and applied to all of them. Toggling each mark by its own state would split a mixed selection in half, which nobody wants. The marks are then selected for you in whichever list they landed in, so the move is visible, not silent.

Nothing promotes a mark on its own. A mark stays yours until you say otherwise, and this command is how you say it. Answering a note of your own is still a note of your own. A mark from another reader stays theirs, whether or not you have replied to it.

The move is written into the history of the mark's own document, naming the sheet and your name if you write one, rather than into the history of whatever document this window opened with.

Sending the copy

Review ▸ Send a Copy for Review… writes the copy that leaves the building. Here is exactly what it contains.

Before the bytes are written, every mark that is going out is given a name in your own document. Both ends have to agree on those names, so the answers can find their marks on the way home, and this cannot be done afterwards: a copy named only in the copy looks matchable but matches nothing. This is the one export that writes to the file you are working in, so your document will want saving afterwards.

What the copy contains:

• The whole document. Every page as it stands: its text, pictures, form fields, links, attached files, printed page numbers and named destinations. A copy for review is the whole document, not an extract.
• The marks you put up for review, and every reply to them, carrying your name if you write one.
• Not the marks you kept to yourself, and not the replies to those. A reply travels with whatever it answers.
• The history, filtered the same way. What the document did to itself, such as being opened, cropped, read or blacked out, stays. What was said about a mark that is not travelling does not, since a copy that holds back forty private highlights but hands over a history describing them has kept nothing back.

A copy for review is not a redacted copy. A black-out in this application is a mark until it is carried out, so nothing is removed from the pages of this copy. If a black-out is one of the marks kept back, it is simply not drawn, and the words it covers are still in the file, selectable and searchable by whoever receives it. When the point is that the recipient must not have the material, use levels or blacking out instead.

The copy is named after the document with for review added, and you choose where it goes. When it is written, the status line reports how many marks travelled and how many stayed here. If anything could not be carried over, it reports that instead, more insistently here than anywhere else, because the copy is already on its way to somebody, and a reader who is not told will find out from them.

Working through what came back

Compare ▸ Next Unanswered (⇧⌘]) and Compare ▸ Previous Unanswered (⇧⌘[) walk the marks in Talk that have no reply. A thread with replies is finished business. A thread without one is the work, and at the end of a review it is the only part that matters.

They ask the Talk list rather than the document, so a mark you never put up for review is not part of anybody's review and is not stepped through. The status line reports how many marks are still waiting.

Both commands wrap around, deliberately. A reviewer who reaches the end and gets nothing has to work out whether that means finished or broken. Landing on the same mark again makes it unmistakable: that is the last one.

Bringing the answers home

Notes ▸ Bring Marks From… carries the marks and the conversations of another copy onto the one you are looking at. Point it at the file that came back.

It matches marks by their words, not by their position on the page. It asks the same engine that shows two editions side by side to find where each mark's words went, so a document regenerated since it was sent, with a section added, a paragraph rewritten, or everything shifted three pages further on, still gets its comments in the right places. See Comparing for what that engine does.

Marks this document already has are left alone, since the marks you shared went out and came home: without this check, everything you shared would arrive twice. Answers to marks that are already here are attached to them in place.

It writes a third document and asks where to put it. The one you are looking at is left exactly as it is, so both sides survive and can be compared. The new document is opened for you.

Then it reports three numbers, not one:

• how many landed on their words;
• how many kept their old place, which happens to an arrow or a drawing that sits over no text at all;
• how many could not be placed, because the passage they were about is gone.

That last group is not thrown away. Anything that said something is kept as a note at the seam where the passage used to be, between the surviving words on either side of the deletion, flagged as unplaced and quoting what it was about. A review that quietly loses a remark is worse than one that refuses to merge at all. A bare highlight with nothing written on it is let go, since there is nothing in it to lose.

Marks as a file of their own

Notes ▸ Export Marks… writes the marks out as JSON, legible without knowing anything about PDF.

Every mark in the document is included, not only the ones you put up for review. Each entry carries the page, the kind, the colour, the geometry, whatever is written on it, the group it belongs to, and the author's name. For a mark that covers words, it also carries the words themselves and the line they sit on, so the mark can find its way back to a document that has been set again since.

Three things are left out, each for a reason: signatures, which carry an image this format has no field for; polygons and polylines, whose shape it cannot yet describe; and proposed form fields, which are not marks anyone made, and would arrive at the other end as coloured rectangles meaning nothing.

Notes ▸ Import Marks… reads such a file back. It adds marks; it never removes any, and importing the whole file is one undo step, the same as pasting several marks at once. Each mark looks for its words first, and falls back to the rectangle it was exported with. The status line reports how many landed that way, since a mark placed by its recorded rectangle is right on the document it came from and meaningless on any other. You are told the count and left to judge it, rather than having those marks dropped for you.

Notes another application kept beside the file

Skim stores its annotations outside the PDF, so a document marked up there looks blank in this application, in Preview, and to anybody it is sent to. Opening such a document here shows those notes without writing anything: a file must not change just because it was opened.

Notes ▸ Import Skim Notes makes them part of the file, where every reader can see them. It is one undo step, and Skim's own copy is left exactly as it was. Importing notes does not mean you are finished with Skim, and deleting the only copy of years of reading is not this application's decision to make.

It also counts how many of the notes sit on no text, and reports that. Nothing ties a Skim note to the words: it is only a rectangle and a page number, so a document that has been set again since leaves them in the header or over blank paper. A note that covers no text is not always wrong, since a figure has no text under it either. That is why this reports the number instead of dropping them.

Watch: a short video for this page is still to come.

Talk · Marks · Comparing · Levels · What is written into the file · Contents