Building Collaborative Notes

This story now lives at Minimal’s blog. To read it over there, follow this link.

It’s hard to design and build collaborative software. Everything is tied together, so a small change in one place has far reaching impact.

It’s also extremely valuable. We’re a social species. Think back to your most memorable meals, favorite travel destinations, and biggest personal breakthroughs. Chances are all of these experiences are significant because of the people you’re sharing them with. Our digital lives are the same.

Designing Minimal’s collaborative writing has been full of great challenges and triumphs. I’m thrilled about the outcome. The journey of designing and building was just as fulfilling.

This brief essay illuminates the process of crafting a collaborative writing experience for Minimal | Writing + Notes. It should be useful for designers, engineers, and anyone interested in how things come together.

Enjoy.

Cloud Sync

Before setting out to build collaborative notes, Minimal already had a robust Cloud Sync system in place. This allowed individual writers to sync notes across their devices. As a writer makes changes on their iPhone, they can trivially pick up where they left off on an iPad and Mac without any hurdle. It’s seamless.

Our goal: different people contributing to the same note. As Writer-A (red iPhone) makes edits, Writer-B (blue iPhone) can see the edits appear as fading rectangles. An intelligent banner at the top indicates the state of the collaboration.

Fortunately, the code for Cloud Sync was well-written. Because it was descriptive and abstract, it was possible to build collaboration directly on top of this personal Cloud Sync layer.

I read through Apple’s CloudKit documentation and roughly understood that we needed to support multiple databases (both a private database and a shared database), and multiple record zones and record types (one type to embody the shared properties of a note, and another to embody personal properties of a note that sync only for the individual).

So I spent about two days simplifying and abstracting the code, massaging Cloud Sync into a content-agnostic sync engine that could handle any data type, and any number of participants. The code actually became smaller, more readable, and more powerful.

A useful metaphor might be found in kitchen utensils. Instead of having a unique tool for every task, most of the things in our kitchen can handle multiple jobs. Our pot can boil water for pasta, or produce soup. A spoon can stir a Negroni, or help with eating ice cream. When we extended the Cloud Sync layer to support collaborative writing, we cleaned out and simplified our metaphorical kitchen equipment, leading to fewer functions that could accomplish more.

Invite Collaborators

For inviting collaborators, I decided to use Apple’s cloud sharing controller. It readily handles most of the edge cases (and there are a lot of edge cases!), allowing writers to start inviting collaborators with the least amount of custom code and custom interactions. This approach also provides a familiar interface, allowing people to adopt the new feature with ease.

Apple’s Cloud Sharing Controller for inviting collaborators and managing shared notes.

I added a note title, a descriptive sharing image, and a fallback url for new writers who have not yet installed Minimal. I also crafted this contextual invite success message as writers join new collaborations.

When writers join a collaborative note they’re met by this screen. The interaction accomplishes two jobs: it provides context, and it grants the app a buffer to finish syncing the note before the writer dives in.

It’s a delightful experience. If my brother invited me to plan a ski trip to Japan in a collaborative note, you bet I’d download that app right away, and I’d probably even start a paid subscription.

Simultaneous Edit

Addressing conflict when multiple people make changes at the same time is by far the hardest problem to solve. There are two avenues of solutions: providing feedback to writers as their notes evolve, and harmoniously resolving conflict so that multiple people can write at once.

For feedback and clarity, I placed a banner at the top of the screen that indicates the state of the collaboration.

The collaboration status banner provides contextual clues. If there is one collaborator, the banner includes initials. When a writer starts typing, the banner reads, “is typing…” preceded by the writer’s initials.

Most of the time, this banner clarifies if a note is collaborative and visible to other people. I think of this as a security feature, or a warning that the note is a shared space.

When someone starts typing, the banner glows and gently pulses, letting the writer know someone is actively working in the space with them.

The banner’s drop shadow gently pulses, subtly drawing attention to the fact that someone is actively contributing to the note.

Typically in software products this kind of banner appears and then disappears to let people know of state changes. For example, connecting to Bluetooth devices on the iPhone or iPad throws a pill-shaped banner that goes away after about 3 seconds. What we’re doing here with a persistent pill-shaped banner is a bit of a violation of standards, but it provides such useful information that I think the deviation is worth it.

Resolve Conflict

Resolving conflict as multiple people make edits at the same time is a major technical hurdle. It’s the most computer-sciency thing I’ve done yet. I loved working through challenge after challenge until the whole thing came together.

In gist, this is how conflict resolution works.

As a note evolves, we keep a simple version history. Specifically, we observe the last ubiquitously synced expression (the version of the note that landed on the cloud and presumably went out to all other devices, or will soon go out to all other devices), the most recent expression on our device, and the proposed expression coming in through the cloud.

Then we use the longest common subsequence to create a story of changes or a “diff story” to describe how the note is evolving.

Longest common subsequence. Writer-A inserts 123 and Writer-B inserts 456. The longest common subsequence is the alphabet.

Here’s the most common conflict: if Person-A inserts “123” and then gets a sync event from Person-B, it looks like Person-B deleted “123.” With the story of changes, however, we know that in fact Person-B’s sync landed for Person-A before Person-B received Person-A’s insertion of “123.” So we keep the “123,” invalidating Person-B’s purported deletion, and move on.

The problem described above is the most common conflict. There are others, and the longest common subsequence and the “story of changes” that it powers provide the solution for just about any conflict I could imagine. It’s powerful. Amazingly, it’s an uncommon case of sophisticated mathematics significantly impacting the human experience with few layers in between.

This story-of-changes approach to finding truthfulness in a collaborative space is similar to the technique anthropologists use to define a culture’s belief system. Anthropologists watch a culture evolve, and pay particular attention to deviations. The deviations and the responses they solicit illuminate the edges of a culture.

Incoming Sync

As sync events arrive, we show the change landing with a beautiful fading rectangle around the new text. The rectangle gradually fades away, creating this wave-like pattern. Writers watch their collaboration take shape.

As Writer-A (red iPhone) makes edits, Writer-B (blue iPhone) can see the edits appear as fading rectangles.

Real Impact

While collaboration is a blast to design and build, it also has real impact. Writers have crafted multi-writer essays, planned trips, composed grocery lists, organized projects, and more.

I’m amazed by the technical breadth required of this new feature — from human design to software architecture and computer science. This amazement and delight surfaces every time I realize that other people in the world are out there using it.

Collaborative writing multiplies Minimal’s value, similar to how a meal tastes better in the company of loved ones. As a gardener might describe it, it’s not the parts that matter — it’s the relationships between parts that define a system and bring it to life.

Collaborative writing just made Minimal more lively, fun, and useful.

Download Minimal for Mac, iPhone, iPad, and Apple Watch right here. To join the beta, follow this link. To read about our design principles, tap here.