In our explorations of universal version control, we’ve found that it’s crucial to have good tools for explaining edits and discussing changes. One key feature for enabling these discussions is inline comments that point to a specific part of a document. Inline comments are so valuable for collaboration that every modern app has them.
Currently, dev teams need to spend time implementing inline comments specifically for their app, even though it’s not a unique differentiator. What if instead there was a universal comments layer across all apps, to save developers work and give users a more uniform experience?
We tried prototyping a universal comments system in Patchwork. It works with the Markdown writing tool we’ve shown throughout the lab notebook, as well as the drawing and spreadsheet tools we showed in our previous post.
When building this system, we aimed to find a minimal API that expresses only the app-specific parts of commenting. We realized that the basic interactions of commenting—typing a message, replying to threads, etc.—are the same for any app, so they should be handled by the Patchwork environment.
What’s unique to each app is the things you can comment on: a range of cells in a spreadsheet, a span of text in a Markdown doc, a set of shapes in a drawing. In our system, we allow developers to describe the things that can be commented on in their specific app using the concept of pointers.
Pointers can refer to part of a spreadsheet, a Markdown doc, or a drawing.
Once the developer has specified a pointer type for a given type of data, all that’s left is to implement a few simple UI affordances to integrate with the Patchwork commenting UI: highlighting the pointers in their app that have comments, as well as reporting out the current user selection to support adding new comments on that selection. The generic Patchwork UI takes care of the rest: letting users enter new comments, showing the list, handling replies, storing the data, and so on. The result is a basic commenting experience with very little work from the developer.
Patchwork stores comments that contain pointers to part of a document.
Beyond that, developers can implement optional UI features which further improve the user experience. For example, when a user selects a comment in the sidebar, the app UI should ideally focus the area of the document pointed to by that comment. Patchwork enables this by passing the currently focused pointer to the app UI, so that it can scroll the focused pointer into view. Even implementing these optional APIs is still less work than building a whole comment system from scratch.
We’ve found that a universal commenting system provides a uniform user experience. For example, we don’t need to learn new conventions for each app; we can press “cmd + shift + m” in any document to leave a comment. In the future, we plan to try building other interfaces on top of the shared commenting layer, like a single inbox for all comments across various tools.
Beyond their usefulness for comments, we’ve found that pointers are a useful primitive in other contexts. For example, we now use the pointers API to power our diff views for version control: when a document is shown compared to a previous version, the app UI gets passed a list of pointers to sections that have changed, so it can highlight additions and deletions. We can also imagine other use cases for them, like highlighting search results across different kinds of documents, or pointing to parts of a document to prompt AI edits.
This is the last entry for now, but you can go back to read the lab notebook from the beginning.
The Ink & Switch Dispatch
Keep up-to-date with the lab's latest findings, appearances, and happenings by subscribing to our newsletter. For a sneak peek, browse the archive.
Instagram Engineering
Shopify Engineering