Beware the thin veneer

A task in need of a tool

It’s common when switching from Subversion to Mercurial (or any other DVCS for that matter) to also switch from a single monolithic repository, to many smaller repositories. When we started work on Kiln, one of the problems we had with Mercurial was the fact that it gave us no guidance on how to set up repositories, so we made a lot of mistakes at first. And, when we figured out how to get set things up the way we wanted, there was no easy way to communicate that with other members of the development team except in a long document with links and screenshots all over the place.

We also realized that while you only had to make the decision about how to convert once, you had to live with that decision, and the need to communicate about it, every day. We couldn’t help but wonder:

Are we the only people struggling with this?

There has to be a better way

This question gave birth to Kiln’s repository organization tools, which include a graphical interface for creating and organizing repositories. These tools helped us solve the problem of communicating how our code was organized by letting us visually relate repositories and tell a story about how our code is organized. There are three levels of hierarchy to help you get organized:

  1. Projects
  2. Groups
  3. Repositories

Each of these levels can be given a descriptive name, and altogether, the structure allows you to express complex work flows with relative ease. Here we are looking at the stable repository for the website component of Kiln:

If I want to build the stable version of Kiln, I can guess that I should check out the stable repositories from each of the groups and build them. The good news is our customers seem to be getting a lot of mileage out of these tools

The thin veneer

But there’s a price to be paid whenever you have a new problem and a new tool to help you solve it: you have to learn them both at the same time. Every choice that we force you to make chips away at the protection that our carefully crafted UI is giving you, and exposes a bit more of the program model. That remains true until the moment you realize that you want the power to make that choice (the user model matches the program model). Knowing this, we spent a lot of time reducing the number of choices that you have to deal with until you find yourself in need of projects and groups:

  • You start with a default project called “Repositories” and un-named repository group. This gives you all of the structure needed to create repositories and import your code
  • You won’t see anything about Projects or Groups in the default interfaces. Instead, we expose those concepts when you go looking for power (Admin menus and “Organize”)
  • The “Browse Repositories” link in the menu bar starts out as a link when you only have one project, and becomes a pull-down menu when you add more.

But we still wanted the functionality to be discoverable. And that means we had to leave some artifacts around for you to find. So while we’ve reduced the obvious complexity, the complexity is still there, just under the surface. In the world of web applications, that surface can get pretty thin sometimes. 

For example, one of the non-obvious consequences of the Project > Group > Repo structure appeared in the URLs that Kiln generates for its repositories. Because Kiln is a .NET MVC application, we have a hierarchical routing pattern for pretty much everything. This is the way that most MVC applications work, but take a look at what a repository URL looks like for someone’s first repository:

This is an area where the surface (UI) is particularly thin. The application is literally exposing the program model through the URL. It has some benefits, like repository URL’s being guessable, but the downside is that we’re hitting you with some weird stuff when you haven’t made a second project or repository group.

The question of how to format these URLs was a small, but much debated, design decision. And while the final design is totally reasonable, it bugs some of our users, and for good reason: they are paying the price of learning about the tool before they’ve had the problem that it solves. In other words, it cracks the thin veneer and leaves you standing in front of the program model with no protection and no guidance.

This is the kind of thing that is hard to see when you’re designing something because you understand the way the web works, and you have the entire program model in your head. A programmer and designer are rarely afraid of to break through the veneer; we’re already distracted by the million tiny decisions going into each interaction we design. But for almost everyone else, the “how” and “why” of a decision like the URLs are just a distraction from the “what” they are trying to get done. Unless I can convince you that you need to know this, I am just going to leave you asking “Why is my URL so long? Shouldn’t I just have to type

Where we go from here

In general, we’re looking for ways to bridge the gap between the user model and the program model. First, we’re looking at a ways to simplify the URL scheme if you haven’t created any other projects or groups (bring the program model closer to the user model). And because many users will be going through the exact same set of challenges that we wen’t through when we switched from Subversion to Mercurial, we’re also looking at better ways to educate users about the problem that the tool is trying to address from within the application (bring the user model closer to the program model). Finally, we’ll pay close attention to those places that the veneer is especially thin, and try to shore it up, or at least give users enough guidance to understand what’s going on.