We spent hours naming this blog post

We spent hours naming this blog post

Have you ever participated in an engineering design session at one of the FAANG companies? It’s a fairly unique experience because engineers do not need to consider many of the typical requirements that force making compromises at smaller companies or open source software. For example, you know that the production environment will be reasonably reliable and that there are ubiquitous and mature systems for storing data, securing service-to-service communication, authenticating users, checking users' permissions, and more. This is the major benefit of engineering at hyperscale: you have the most sophisticated foundation on which to solve your problem. Now all that’s left is to focus on the problem at hand. What could possibly go wrong?

Step into the Design Room

Put five of the smartest people in a room for an hour and tell them to solve a relatively simple problem: what kind of solution do you think they will have when they leave the room?

  • the naive idea that solves the 80% use case
  • the reasonably complex idea that covers 95% use case
  • the most flexible abstract idea that covers all possible changes in scope

Every Xoogler (former Googler) I’ve ever met would tell you with confidence that the last option most often emerges at the end of the meeting. But, shouldn’t this be a good thing? Not only is the problem solved, but there’s also flexibility for the product to change and still be successful, right? The problem lies in the fact that these solutions were designed with engineering as the sole focus. However, to create a successful product outside of Google, there are more requirements to take into consideration than elegant software design.

A rose by any other name would just be more vague and confusing

The names used to describe the data in your product are as important as the internal design of the product itself. The more “meta” the name, the more difficult it will be for users to understand. Are you still discussing the problem domain or are you now discussing “nodes and edges” or “objects and types”? Sometimes these terms are the domain of the problem, but often it will become clear that you’ve lost sight of the user’s perspective. Consider the following hyperbole: you could describe “a particular monoidal property of the category ℕ” or you could simply say “addition”. The former is only understood by mathematicians that already know “how the sausage is made” while the latter you could discuss with your coworkers' children. At the end of the day, software products provide value by abstracting away the complexity of the solution so that others can apply that solution without reinventing it themselves.

Reversing the abstraction

At Authzed, we’ve built a product inspired by the Zanzibar permission system at Google. Zanzibar has been publicly documented in a research paper and, as such, uses terminology that makes sense for engineers building such a system, but has very little focus on how an intuitive end-user experience could be created from such a system. Your intuition would lead you to think that a permission system should frequently have to mention its core concept: permissions. However, outside of the introduction and conclusion of this paper, the word permission is only used twice: both in the same example. The Zanzibar paper avoids using this term almost entirely because it represents permissions as paths through a graph that they call relations. Instead of permissions, the core API objects used in Zanzibar are called Tuples, which define a direct relation between two objects. It is extremely non obvious that graph databases are usually built on top of a concept called a “tuple store” and that relationships in graphs are stored as “Tuples” (or “Quads” when there’s an enforced schema).

While our engineering team has previously worked on the internals of relational and graph databases, it is entirely unreasonable to require that our users also have that same level of understanding in order to design their own permissions systems. As a result, we are now in the process of updating our terminology and iterating our API to make a more approachable system. We think this signals a level of maturity in our development that other Google-inspired software like CockroachDB (Spanner) and Kubernetes (Borg/Omega) have also acknowledged. Our goal is to have an experience that has the intuition of the 80% solution, but is also capable of the last 80% for those that need it.

We invite everyone to review our new terminology and help provide feedback. We take into consideration all user perspectives: you need not identify as a backend engineer or even an engineer at all. Afterall, solving our users' problems is what drives us to build a better product.

Recent Articles
Maintaining a Stable Protobuf API
How we're avoiding breaking users without compromising developer UX
We spent hours naming this blog post
Why names matter regardless of how technically sophistocated a product is.
Joining a Startup During a Pandemic
My experience starting at Authzed during the pandemic.