How we created Sourcegraph’s product design principles

Quinn Keast

product design principles graphic

As we’ve grown over the last few months, the Sourcegraph design and product teams have found ourselves having more discussions around product and design decisions. This is a common challenge for design teams everywhere: there are often many valid ways to solve a problem, each with its own set of tradeoffs and assumptions. A small team can rely on intuition, experience, and shared trust to make decisions in these moments. But gut instinct doesn’t scale.

The design and product teams were at an inflection point. That’s why we decided it was time to come together to define our product design principles. I’m going to go into how we did this and what principles we settled on, but first I’ll cover some basics:

What are product design principles?

Product design principles are a set of statements co-created by the team to express a shared vision and values for the product.

A strong set of product design principles gives the team a way to make consistent decisions based on a shared idea of what we’re trying to achieve. They introduce constraints that help reduce ambiguity, particularly when there’s more than one possible solution to a given problem. They also give us a way to capture our commitment to inclusion at every step of the design process.

Who uses product design principles?

While they might be called product design principles, they’re for everyone in the organization.

Designers use design principles to guide their explorations and outcomes. Product managers use design principles to shape priorities and features. Developers use design principles as a lens to collaborate on design, from discovery to delivery.

Design principles and design patterns are often conflated. Where design principles are simple, broadly applicable, and capture our shared vision and values, design patterns are the tangible and repeatable expression of our principles in combination with heuristics of good design and usability.

Design principles don’t change often, as they reflect a core truth of who we are. Design patterns change over time to meet new needs, technology, and trends.

How we defined our product design principles

At Sourcegraph, we’re fully remote and globally distributed. Our product and design teams span 13 time zones. That’s why we prioritize asynchronous collaboration together with thoughtful moments of real-time collaboration.

We wanted to involve product designers, product managers, and engineers throughout the process to co-create our design principles. To make sure we could create the best collaborative environment, we planned a process that would start asynchronously before bringing us together for a real-time workshop when we needed an immediate feedback loop.

The process

1. Aligning on our goals and conceptual understanding of principles

We created a shared working doc where we broke down our understanding of design principles, how they’re used, and how we would use them. This gave us a target and alignment around a shared conceptual understanding of principles and what we were trying to achieve.

2. Digging in individually to reflect on principles in action ahead of the workshop

Ahead of the workshop, we did some homework. Each member of the team went off to explore and reflect on how other organizations defined their principles, and how those principles were reflected in their products.

3. Workshop

To bring us together and create a quick feedback loop, we facilitated a workshop with designers, product managers, and engineers. As a warm-up activity, everyone took turns sharing reflections from their homework to get everyone in the right frame of mind.

Then, we spent some time individually generating ideas, before collectively finding themes emerging across the team. Everyone joined in to group and label these themes, which we then used as the basis for a guided discussion around each theme.

Finally, we shifted back to an asynchronous workflow to cast anonymous votes for the themes that resonated most strongly with each of us as individuals.

Uncovering themes among ideas

4. Continuation and refinement

One of the trickiest parts of a collective activity is bridging the gap between collective work and cohesive outcomes.

To keep us moving forward, one member of our team took the outcomes of the workshop—the themes, the notes from our discussion, and the voting—and wrote a first draft of our potential product design principles. This artifact became the basis for further continuation and refinement.

5. Sharing and collecting feedback from the whole organization

Once we all felt strongly that our product design principles captured our team’s vision and values, we shared our proposed principles as an RFC with everyone at Sourcegraph, which you can now read too.

Sourcegraph’s product design principles

  • A personal tool within a larger workflow
    Sourcegraph is a powerful yet personal tool that exists within a larger workflow. Design for familiar patterns with thoughtful defaults, while embracing personalization and adaptability.

  • Made for everyone
    Our purpose is to make it so everyone can code. This demands we make Sourcegraph accessible and useful for all developers through universal, inclusive design.

  • Gracefully manage complexity
    Sourcegraph supports complex product requirements, but also empowers users to manage this complexity for their individual needs.

  • Code as content
    More time is spent reading than writing code. Elevate the craft of code as content.

  • Trust is earned
    Sourcegraph is the source of truth for developers working on and learning about their code, but this trust is earned. Accuracy, transparency, recency, and honesty together work to uphold this source of truth.

  • Create momentum
    Help developers create and maintain flow. To do this, Sourcegraph must be fast in every way. We design purposefully to help users iterate and build momentum.

We’ve published our product design principles in our open handbook.

The path forward

Now that our team has these product design principles, we’re using them in our work to make better decisions faster. Over time, our team and developers using Sourcegraph in their work will see these principles reflected as these decisions accumulate.

If your company doesn’t have product design principles, consider creating them together! Sourcegraph is an open company, and so our process, artifacts, and resources are all available to you.


Get Cody, the AI coding assistant

Cody makes it easy to write, fix, and maintain code.