Annotations allow you to easily communicate policy or other content changes right alongside new or updated content. Employees see them when they view a new version of your handbook and again if they're asked to sign an acknowledgement.

Imagine that every time you updated your handbook, 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 handbook. 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 handbook so employees could easily flip through all the changes.

Annotations work just like that - but digitally! And because they're digital, we can add 2 cool enhancements to the paper sticky note scenario:

Annotations are personalized for every employee based on the last version of the handbook 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 one 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/section in detail.

You can also create annotations that are only for other handbook editors. These are viewable within a section's Version History within the Blissbook content management system. It's a great way to make sure all collaborators are on the same page regarding policy changes.

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 handbook scenario described above, if you do not create an annotation for a changed section, 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 your handbook.

Creating Annotations

There are 2 ways to create an annotation.

#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:

#2: When you publish a handbook (after you've launched), you'll be given the opportunity to annotate any changes that have been made. The screen looks like what you see above and annotations work the same way.

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, a preview of your handbook will open.

Annotations appear in the bottom left corner of the screen just like they'd be presented to someone who's viewing your handbook. 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 handbook and did not need to sign.

You can adjust what the box (and what the rest of the handbook) looks like by changing how you are previewing the handbook via the preview settings bar at the top of the screen.

If you preview the handbook as a person, you'll see exactly what they would see.

Viewing Annotations

People viewing a handbook will see a personalized list of all possible annotations.

For those who do not need to sign anything:

If someone has never viewed the handbook before, they won't see any annotations since, to them, the handbook is brand new and has never changed.
If someone has viewed the handbook 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 handbook before, they won't see any annotations since, to them, the handbook is brand new and has never changed. They'll just be asked to sign.
If someone has viewed the handbook 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 handbook 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

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 handbook.

Once you turn off or de-activate an annotation, it can no longer be seen within the live handbook 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.

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 related areas of our business. For this reason, we've reduced the new employee referral commission from $5,000 to $1,000."
Bad: "We've 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.

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."