Annotations allow you to easily communicate content changes to audience members (employees) right alongside new or updated content. Employees see them when they view a new version of a document and again if they're asked to sign an acknowledgement.
Imagine that every time you updated a document, you printed out a physical paper copy for each employee. And imagine that when you did that, in order to give those employees a little bit more information about the changes, you stuck a sticky note to some or all of the updated policies within the document. The note could describe why the policy changed, where to look for the updated language; it could summarize the changes, or it could say something else entirely. Last, imagine that the corner of each note stuck out from the side of the paper document so employees could easily flip through all the changes.
Annotations work just like that - but digitally!
Because annotations are digital, we can add 2 useful enhancements to the sticky note analogy:
Annotations are personalized for every employee based on the last version of the document or policy they viewed. They'll see all the sticky notes relevant to them since then, and none of the ones that aren't.
If an employee is asked to sign an acknowledgement, and they've signed before, they'll see all the sticky notes since the last time they've signed. This makes it really easy to understand exactly what they're signing off on without having to re-read every policy or section in detail.
New: Annotations on Policies in the Policy Library
Annotations get a big upgrade in the policy library, as they are now attached to selections of text instead of entire sections/policies. This allows you to lead employees to changes much more directly, which can save significant time. See below.
Before we get into the details...
Just like if you didn't write and stick a sticky note to a policy in the imagined paper document scenario described above, if you do not create an annotation for a changed section/policy, employees will simply see the new/changed content without any indication that it is new or has changed. Employees always see the latest published version of a document.
Creating Annotations in Documents
There are 2 ways to create an annotation inside a document.
#1: Within the editor, while you're editing content.
Choose "Add Annotation" from a section's ••• menu:
Or, if a section has a change, click the change notification "sticky note" icon to the left of the section's title:
This will open that section's version history, where you can add an annotation for Viewers/Signers or Editors/Collaborators:
"For Collaborators" annotations are only for other document editors. These are viewable within a section's Version History. It's a great way to document a change for others or future you.
#2: When you publish a document (post-launch, v2+), you'll have the opportunity to annotate any new or changed sections during the publishing workflow:
It work the same way as described above.
Creating Annotations in Policies
Annotations in the policy library are attached to selections of text, which makes it easier for employees to understand changes.
They're super easy to make! Select the text you want to annotate, and choose "Annotate" in the contextual menu that pops up:
Write your annotation and click the submit button:
Previewing Annotations
If you click the "Preview" button next to the "Publish..." button within the editor or the preview button at the bottom of the annotations page within the publishing flow (or any other "Preview" buttons), a preview of the document will open.
Annotations appear in the bottom left corner of the screen just like they'd be presented to someone who's viewing the document. The box is different depending on whether or not the viewer needs to sign an acknowledgement.
By default, this box will show all active annotations that any employee could possibly see if they were viewing the document and did not need to sign.
You can adjust what the box (and what the rest of the document) looks like by changing how you are previewing via the preview settings bar at the top of the screen:
If you preview the document as a person, you'll see exactly what they would see.
Viewing Annotations
People viewing a document will see a personalized list of all annotations.
For those who do not need to sign anything:
If someone has never viewed the document before, they won't see any annotations since, to them, the document is brand new and has never changed.
If someone has viewed the document before, they'll see a list of the new annotations since then.
Note: Annotations must be dismissed by viewers via a "Got It, Dismiss" button:
If the viewer doesn't dismiss a section's annotations, they'll keep showing up unless they're de-activated by an Admin (see below).
For those who need to sign:
If someone has never viewed the document before, they won't see any annotations since, to them, the document is brand new and has never changed. They'll just be asked to sign.
If someone has viewed the document before, but have never signed, they'll see a list of the new annotations since the last time they viewed.
If someone has signed the document before, they'll see a list of all annotations that were created since the last time they signed (even if they've previously dismissed them).
Signing an acknowledgement dismisses all annotations.
De-Activating Annotations
At some point, you may need to turn an annotation off, perhaps because:
There's a new change that renders an old annotation obsolete or unnecessary
There's a spelling or grammatical error in an annotation
There isn't a need to "clean up" or delete "old" annotations, as each individual viewer cleans them up by clicking "Got It" or by signing, and new employees never see your older annotations.
In a Document
You can turn off an annotation in a section's Version History (click a section's ••• menu, then choose Version History), or within the publishing process. Click the ON/OFF toggle:
Turning off an annotation counts as a change to a section, so you will need to publish that section in order to de-activate the annotation on your live document.
In a Policy
To open an existing annotation, either (a) click the blurple-highlighted text within the policy...
...or click the Annotations button...
... to open the annotations tab in the sidebar:
Once it's open, hover over the annotation you want to remove, click the ••• menu, then choose Remove Annotation:
You'll need to publish the policy to push this change out to an audience.
Once you turn off, de-activate, or remove an annotation, it can no longer be seen within the live document by any viewer no matter what.
Best Practices for Writing Annotations
Be specific about what changed.
Good: "Employees now get 18 vacation days instead of 15."
Bad: "We changed the number of vacation days employees get."
Good: "Added 'pregnancy status' as a protected class."
Bad: "Updated the list of protected classes."
If you've made several unrelated but specific changes throughout a section, add content for each change (or, even better, do a separate annotation for each change via the policy library).
Good: "Information about change A. Information about change B. Etc."
Bad: "We updated several items, please read the policy."
If you've made so many changes to a section that it's impossible to describe everything specifically, include a reason for the overhaul.
Good: "After acquiring WidgetCo, it's important that we combine our policies to become one cohesive organization. Although the spirit of this policy remains intact, there are several changes throughout. Please read it thoroughly and talk to your manager or HR if you have any questions or concerns."
Bad: "We combined the WidgetCo version of this policy with the Acme version."
If a change is inconsequential, don't add an annotation at all. This adds noise and reduces the desire to read through actual changes.
Good: <silence>
Bad: "Fixed a few typos and misspellings."
If a policy change can be perceived by employees as a loss, give a reason for the change. Any reason is better than no reason!
Good: "In an effort to achieve our mission of an affordable time machine for the mass market, we need to reduce the cost to make it. This means trimming costs in all areas of our business. For this reason, we've reduced the new employee referral commission from $5,000 to $1,000."
Bad: "We reduced the new employee referral commission from $5,000 to $1,000."
If a change is hard to find within the content, give viewers a hint (or, even better, annotate within the policy library to do a separate annotation for each change).
Good: "New mothers now get 15 months instead of 12 to take breaks to express milk. Please see the 3rd paragraph underneath the 'Breaks for New Mothers' heading for more information."
Bad: "We've increased the timeframe for new mothers to take breaks to express milk."