Blog Home
How Almanac’s engineers brought code review to documents
Martin Denyer shares the story of bringing Version Control Mode to life.
Andrea Michaelian
Andrea Michaelian
Head of Product Marketing
min read

Software engineers use a code review process every day. Code changes are written on branches, diffs can be reviewed, and new code is merged down – with defined version control along the way.

Why couldn’t that same process apply to rich text docs? Martin Denyer, a full stack engineer at Almanac, shares the story of bringing Version Control Mode to life.

“What we heard from our users is that they didn't always want someone to make edits to their documents directly. They wanted to have control and approval over what changes were made.

It seemed obvious from our point of view as engineers, the solution to that problem is branching and version control – that is a path well trodden when it comes to software development. But there was no tooling on the market that could support that for the types of documents knowledge workers create and consume every day.

The way we came to Version Control Mode was by asking ourselves ‘how do we get a similar experience for people that are collaborating not on code, but on rich text documents?’”

While Version Control Mode was released in May 2023, the foundation for it was laid a year prior with the release of Layers.

Layers introduced the concept of “branching” into editing and collaborating on docs in Almanac. Editors can create a private Layer to propose track changes directly to the document owner and invite others to their Layer to comment and review, all without affecting the main document.

Layers on an Almanac doc

In building Layers, Martin recalls the team didn’t start with a distinct goal in mind.

“It wouldn’t be possible to build Version Control Mode without the concept of branching in place. So that kind of was the first challenge.

Layers was one of those incredibly fun features to work on where in the beginning, we knew the problem we wanted to solve, but we weren’t actually entirely sure how we were going to solve it. Or even if what we wanted to build was possible from a technology perspective.

But you know, that's the joy of working on these kinds of things. And that's why it interested me in particular.”

After many rounds of iteration, internal testing, and user feedback, Layers was released to Almanac users in September 2022. The team then set their sights on building Version Control Mode.

Enabling Version Control Mode allows document owners and editors to "lock" a doc, so that any changes requested by viewers must be made via a Suggestions Layer.

“From a technical point of view, it became much easier to create Version Control on top of docs once we had Layers.”

The team also wanted to make it extremely easy to track the history of each version of a document, similar to how engineers can quickly diff and revert to prior versions of code. They built Version Control Mode such that each Suggestions Layer merge will create a distinct event in the doc’s Activity Feed. Anyone with access to the doc can click into the event to view the diff of what changed with each merge.

Editors can also add a commit note when merging a Suggestions Layer, to provide even more context on the changes.

“What we're particularly proud of is the big bet we made with introducing Layers first, to then be able to build Version Control Mode. Putting so much effort into the technology behind Layers paid off, because we were able to roll it into such an impactful feature for our users.

I think that for us has been a source of immense pride. Seeing users diffing and merging with rich text content has just been a highlight of my career so far. It's been a lot of fun."

You Might Also Like

Join a live demo of Almanac
Learn how Almanac works in under 20 minutes.
Save my seat