The Future of Software


Most companies assume that management ability and individual contributor ability
are separate skillets that don't really correlate with each other (and are
perhaps slightly negatively correlated).

For example, people assume that the software engineers who are the best at
writing code won't necessarily be the best at managing other software engineers.
The best designers won't necessarily make the best design managers. The best
accountants won't make the best accounting managers. And so on.

As a result, this is how most companies end up thinking about talent:

![A venn diagram showing bad management practices.](/bad-venn-diagram.png)

Most companies assume even if this venn diagram overlaps a bit, the circles are
mostly separate. Some people are great individual contributors, and others are
great managers. It's rare to be both, and if you're neither, you might want to
start looking for another job!

It's the "great" managers who go on to occupy leadership positions, while the
individual contributors usually stay individual contributors. This is especially
common in software engineering, where the "management track" is explicitly
separated from the "individual contributor" track.

Other job functions may not make this distinction explicit, but you'll see it
play out if you work long enough in corporate America. The people who ascend the
management ranks and become directors, VPs, and CxOs almost always do so because
of their (perceived) management abilities, not usually because they are
excellent at their craft, whatever that may be.

But actually, this misunderstands what makes a great manager. A great manager
must be _both_ a great manager _and_ a great individual contributor. It's true
that just because you're a great individual contributor doesn't also mean that
you'll be a great manager.

However, the one thing I'm certain of is that if you aren't a great individual
contributor, **it is impossible for you to be a great manager**. Let me repeat
that another way. There is no such thing as someone who's a subpar individual
contributor but a good manager. To be a great manager, you must _first_ be a
great individual contributor.

But don't just take my word for it. Here's what three of the greatest CEOs in
history have to say about it:

> I think that every leader should be an expert in what they’re leading. There
> should be no people managers in the entire company.

_- Brian Chesky_

> You know who the best managers are? They're the great individual contributors
> who never, ever want to be a manager, but decide they have to be a manager,
> because no one else is going to be able to do as good a job as them.

_- Steve Jobs_

> I strongly believe that all managers in a technical area must be technically
> excellent. Managers in software must write great software or it's like being a
> cavalry captain who can't ride a horse!

_- Elon Musk_

These great CEOs all agree that the best managers are also great individual
contributors. What I would add, however, is that being a great individual
contributor is not enough to be a great manager. It is necessary, but not
sufficient.

A great manager must also be, well, a great manager. She must know how to hire,
fire, promote, communicate, organize, and galvanize. And it's true that many
people who are excellent individual contributors lack those skills.

So corporate America is correct that being a great individual contributor does
not necessarily make someone a great manager. But they draw from this the wrong
conclusion. They assume that this means that it's being a great manager is
simply separate from being a great individual contributor, and that you can do
one without the other.

But this is wrong, because actually the venn diagram looks like this:

![A venn diagram showing good management practices.](/good-venn-diagram.png)

To summarize: Only some individual contributors are great managers, but all
great managers are great individual contributors.

It is those rare individual who have both gifts - who are both great at their
craft _and_ talented leaders - who should lead your company if you want to
succeed.


What people get wrong about managers and individual contributors.

The Myth of Great Managers


In 1959, Robert Noyce invented the microchip at Fairchild Semiconductor,
ushering in the computer revolution that has been continuously unfolding ever
since. The microchip made it possible to build smaller, cheaper, more powerful
computers, paving the way for a generation of new consumer electronics devices -
in the beginning, simple products like calculators and digital watches,
eventually much more consequential technologies like the PC and the smartphone.

Nine years later, Bob Noyce and Gordon Moore went on to found Intel, Fairchild’s
spiritual successor. Intel’s chips were an integral part of the personal
computing revolution. They could be found in the Apple Macintosh and IBM PCs, in
cloud data centers, and in all manner of other consumer electronics.

Gordon Moore famously predicted that the number of transistors in an integrated
circuit would double roughly every two years - Moore’s Law. Thanks largely to
his own efforts, this prediction came true, and computing power has improved at
an exponential rate for the last fifty years, enabling applications today that
would have been unthinkable a few decades ago.

One such application is the neural network. In Yann LeCun et al.’s seminal 1989
[paper on backpropagation](http://yann.lecun.com/exdb/publis/pdf/lecun-89e.pdf),
which represents the practical birth of deep learning, they trained a tiny
~1,000 parameter neural network for handwritten digit recognition. The training
took three entire days to train on a state-of-the-art workstation. Today it
takes less than 2 minutes on a Macbook Air.

As much as anything else, Moore’s law paved the path from these tiny toy neural
networks to today’s large language models.

I see a lot of parallels between the microchip and the LLM:

1. I expect that LLMs and deep neural networks writ large will probably improve
   every single year - perhaps exponentially - just like microchips did. Just as
   compute got cheaper and more powerful, so will intelligence.
2. I expect that LLMs will be a key ingredient in a generation of new consumer
   applications, just like microchips were a key ingredient for personal
   computers and smartphones.
3. I expect, however, that the companies who invent those applications will not
   be the same companies who build the LLMs, just as Intel did invent the PC.
4. I expect that building this next generation of applications will be largely a
   matter of creating better user experiences and helping average people to
   integrate this powerful technology deeply into their lives and their work,
   just as PCs helped average people harness the power of computers.

I think that point #4 represents a massive opportunity, and that the next crop
of generational technology companies will be built by solving this problem.

To extend the analogy between microchips and LLMs, I think ChatGPT is to the LLM
as the calculator was to the microchip - merely the first, simple consumer
application of a technology that will pale in comparison to future applications
like the PC. The PC for the LLM era has not yet been built.

ChatGPT, like a pocket calculator, is profoundly useful and a massive upgrade
over what was previously available, but it’s also very limited if you think
about it:

- It only speaks when spoken to. It will never proactively do anything for you.
  It won’t summarize what you’ve missed at work while you were on vacation. It
  won’t sit on the phone with your utility company for you. It won’t pay bills
  on your behalf.
- It doesn’t have access to data about your life and work, at least not by
  default. We’re starting to solve this with tools, function calling, and
  retrieval augmented generation (RAG), etc. but these are fairly limited and
  mostly just available to developers who program their own assistants.
- It can’t truly learn over time and take into account large amounts of
  contextual information in the fluid way that a human can. RAG, fine-tuning,
  and enlarging context windows aren’t quite an adequate solution here. A human
  interlocutor doesn’t need any of these tricks to remember its last interaction
  with you. We just intuitively recall all relevant details because our neurons
  update in realtime.
- It can only do one thing at a time. One of the most important features of
  modern computers is that they are multithreaded. You can listen to Spotify and
  check your email at the same time. Why shouldn’t your LLM assistant be
  multithreaded too? Shouldn’t it be simultaneously responding to your emails,
  managing your finances, and helping to get you that elusive reservation at
  Polo Bar?

So, to summarize, the next evolution of AI assistants needs to be:

- Proactive
- Integrated with external systems
- Contextually aware
- Multithreaded

This isn’t an exhaustive list, of course. Portability and multimodality are
helpful too, which is why we’re seeing an explosion of new wearable AI devices
like [Rabbit R1](https://www.rabbit.tech/) and the
[Humane AI Pin](https://hu.ma.ne/) that you can talk to as you go about your
daily life.

All of these attributes are even more important in a B2B or enterprise setting.
In fact, I suspect that the upside for LLMs in B2B applications is even greater
than the upside in consumer applications.

Giving your employees a creative assistant like Github Copilot or ChatGPT is all
well and good, but the human being at the keyboard is still the rate limiting
factor. The real value will be created by embedding LLMs deep inside of your
business’s digital infrastructure and allowing them to proactively perform
thousands of actions in the background.

> Whenever logical processes of thought are employed - that is, whenever thought
> for a time runs along an accepted groove - there is an opportunity for the
> machine.

\- Vannevar Bush, _As We May Think_, July 1945

Every business in America is full of processes that are formulaic enough that
they can now be done by an LLM, and for formulaic processes, an LLM is a perfect
fit. Their precise instructions can be tweaked and introspected. Their outputs
can be conformed to the correct format. And, perhaps most importantly, they are
lightning fast and dirt cheap compared to humans.

But an assistant like ChatGPT is not the right vehicle for automating these
formulaic processes. We need something more - something that is proactive,
integrated with external systems, contextually aware, and multithreaded.

I believe that solving these problems can unlock the power of AI for the
American economy, the same way that graphical user interfaces unlocked the power
of computers and web browsers unlocked the power of the internet. The company
that invents these new capabilities has the potential to transform the business
world and reap huge rewards.

And, as mentioned, this company is unlikely to be Open AI or Mistral or Google
or Microsoft, because history has shown that the company that creates the
platform isn’t usually the company that builds the killer app on the platform.

- Intel built the microchip, but they didn’t build the PC (Apple, IBM, and
  Microsoft did)
- Oracle built the database, but they didn’t build the CRM (Salesforce did)
- Apple built the smartphone, but they didn’t build ridesharing (Uber did)

So that’s what I’ll be working on building. We’ll see what happens.


The New Microchip


Today was my last day at Yext. Starting tomorrow, I’ll be working on cofounding
a new company. (More on that in a future post.)

I spent today looking through old slack messages, emails, and documents,
recounting the last half decade of my life. Some lessons stood out to me:

1.  Politics kills good ideas. Many of my biggest regrets were things we could
    have accomplished but didn’t because of internal dysfunction. There were a
    lot of instances of this: products and features we knew - or at least I
    knew - that we could deliver, but we didn’t because two teams couldn’t get
    on the same page, or because politics got in the way. A lot of promising
    projects die this way, and I am committed to not letting this happen as
    often at my next company.
2.  You will make a lot of mistakes. It’s inevitable. You should assume that
    some significant percentage of the work you do will be thrown away. That’s
    the only way to find what does work - by doing a lot of what doesn’t work.
3.  Trust your gut. For many of the projects I worked on that failed, I had an
    uneasy feeling about them from the very start - like we were doing them for
    the wrong reasons, or they had a bad technical foundation. I wish I had gone
    with my gut more in those instances. My instincts are certainly not perfect,
    but looking back I was surprised how good they turned out to be.
4.  Compound interest matters a lot. Something that grows by 30% each year will
    be huge before long. Therefore simply staying at something and incrementally
    improving for enough years in a row can be a very successful strategy. But
    it requires patience.
5.  The days are long but the years are short. Looking back on the most
    important contributions I made these past five years, many of them were
    documents or prototypes that I completed in just a day or two. A few days of
    intense focus and productivity can be enough to change your life. At the
    same time, I’m also astonished by how little actually happens in a year, how
    fast they go by, and how easy it is to accidentally squander them. The best
    way to make sure that your year is well spent is to make sure that each day
    within it is well spent and, importantly, that each day points you in the
    same direction. (See previous point about compound interest.)
6.  When it comes to big, ambitious projects, the best predictor of the
    project’s success is its leader. There is a certain type of ambitious,
    energetic, and highly competent “rockstar” leader that can get these
    projects done. Often, when they leave or when they shift their focus
    elsewhere, progress not only slows, it stops completely. It’s extremely hard
    to make big changes without one of these rockstar leaders. Lesser managers
    can keep things afloat and maintain the status quo - in fact, they are often
    better at this than the rockstars are - but they cannot do big, ambitious,
    company-changing projects.
7.  Most things follow a power law distribution. A tiny percentage of your
    customers will account for the bulk of your revenue. A tiny fraction of your
    ideas will deliver the bulk of the value you create. A tiny fraction of the
    people at a company will do the bulk of the important work. This pattern
    emerges again and again in life and business and technology. There seems to
    be no avoiding it. So you need to accept it, which means focusing on getting
    the most out of that small percentage of people and ideas that matter most.


What I Learned at Yext


For the last six months, my team and I have been building
[Yext Chat](https://www.yext.com/platform/chat) - a brand new SaaS product for
building customized, steerable chatbots powered by generative AI.

For this project to be successful, we knew we needed to be _agile_ - to move
fast and be flexible. The technology and market were rapidly evolving, so it was
crucial to be nimble and experimental, not beholden to any particular master
plan.

The word “agile” means different things to different people, but for most
software engineers it evokes the [Agile Manifesto](https://agilemanifesto.org/).

The Agile Manifesto was written in 2001 by a group of software engineers seeking
a more flexible approach to software development in contrast to the rigid
“waterfall” method that dominated at most software companies at that time.

Their manifesto outlined four core values:

1. Individuals and Interactions over Processes and Tools
2. Working Software Over Comprehensive Documentation
3. Customer Collaboration Over Contract Negotiation
4. Responding to Change over Following a Plan

All good advice.

However, these days, when people talk about the “agile method” they often get
way too bogged down in the rituals and the dogma. My eyes glaze over whenever I
hear the words “scrum”, “kanban”, “sprint planning”, or “retro”. I don’t know
what half of that stuff is and I don’t think it matters. I think it distracts
from the principles that _actually_ make a software team agile.

In fact, the rituals of the agile methodology can become their own form of rigid
bureaucracy when blindly followed. Engineers can too easily become slaves to
their Jira boards, spending more time assigning story points or conducting
sprint planning than they spend building software for their customers.

What I’ve learned is that there is no single process or blueprint you can follow
to be agile. Agility will look different for each company and each team. But
there are still principles you can follow to make your team agile - to maximize
the speed and efficiency with which you deliver great software (and have a lot
of fun while doing it).

Here are those principles as I’ve learned them over the last six months.

### Let Process Evolve Naturally

The first principle is to let processes evolve naturally to meet the needs of
the team. The processes exist to serve the team, not the other way around.

When I say “process” I’m referring to all of the various tools and rituals we
have at our disposal for keeping track of work and staying on task. This
includes…

- Your issue tracking tool (Jira works, Linear is better)
- Your Git workflow and code review process
- The medium you choose to formalize your plans (“the spec”)
- Your cadence of meetings, standups, retros, etc.

I’ve learned that there is no single right way to do any of these things. It
depends entirely on the nature of the team and the nature of the project. For
example, while we were building Yext Chat we found daily standup meetings
indispensable, because everyone’s work affected everyone else’s and we needed to
stay constantly abreast of what everyone else was doing. But for a more mature
product where each person’s work naturally becomes more siloed, a daily standup
might be a waste of time.

It’s possible to have too little or too much process, and I’ve seen teams suffer
from both. You might have too little process if you find that people are doing
duplicative or contradictory work. For example, if you end up with nasty merge
conflicts that take days to disentangle, that’s probably a sign that there was
too little process and that the team was not planning far enough ahead.

However, the more common failure mode that I’ve seen is that there is _too much_
process, not too little. This happens because process, like household clutter,
quietly accumulates over time, and after a while everyone forgets why the
process exists in the first place.

My best advice for addressing this “process clutter” is to occasionally do
“process spring cleaning”, which involves deleting standing meetings, getting
rid of established processes, and cutting red tape wherever possible.
Inevitably, you will find that _some_ of the processes that you got rid of were
actually important, but you’ll also find that many of them were no longer
necessary, perhaps because they were imposed during a different time when the
team had different needs.

That’s okay! You can always add a process back. You can always put meetings back
on the calendar. But if you _never_ get rid of process, then gradually so much
of it accumulates that it’s impossible to get anything done. This is what turns
innovative startups into boring bureaucracies, and you must stave this off for
as long as you can.

### Write Things Down

The written word is highly underrated in the modern workplace. I find that
complex, important decisions are basically impossible to make unless someone has
written a document which can serve as the foundation for making those decisions.
Otherwise you end up talking in circles and accomplishing nothing.

If you ever find yourself in such a meeting, end it immediately, designate one
person to “own” the decision, and have this person write a narrative memo
explaining the decision. Reconvene everyone and force them to read the document
in silence and then discuss the decision.

You might think that sitting down and writing a narrative memo contradicts the
spirit of speed and agility, because writing is slow and time-consuming. It’s
hard to do good writing in a hurry.

But even though writing is hard and time-consuming, the time it takes to write
down an idea is _far_ less than the time that writing will _save you_ in the
future. Writing prevents you from wasting time in interminable meetings or
bottomless Slack threads trying to reason through complex decisions. I’d much
rather take the time to write a good comprehensive treatise on a subject than
spend hours in meetings trying to muddle through a complicated decision.

You should also make sure to memorialize each decision you make in writing.
Ideally you should do this live, while everyone else is watching, and confirm
that everyone agrees with what you’ve written. This serves two purposes. First,
it ensures that you don’t forget the decision you’ve made (which happens all the
time when you neglect to write things down).

But second, it helps to uncover hidden areas of disagreement or confusion.
People often _think_ that they’re in agreement at the end of a long
conversation, but then discover that they actually aren’t because they
misunderstood what the other person was saying. Memorializing a decision live
can help uncover these misunderstandings quickly, which is far better than
uncovering them weeks later.

Clear writing is clear thinking. So whenever your team’s thinking becomes muddy,
the best way to clear it up is by writing things down.

### Make Prototypes

However, as much as I love writing, written English is not always the best tool
for exploring new ideas. Often _code_ is the best tool for that job. If you are
trying out a truly novel idea, you’re often better off just building the damn
thing instead of writing a long document explaining now it might work.

I’ve found this to be especially true in two cases:

1. designing complex user interfaces and
2. designing complex, algorithmic product features.

For building complex UI, our company used to write out tedious “use cases” or
“user stories” for every possible aspect of the interface.

A use case would read something like this:

- The user clicks onto the “Home Screen” in the navigation.
- The user hovers over the “Add Site” button.
- After 250 ms, a tooltip appears.
- The tooltip reads “blah blah blah”

Don’t do this! It’s pointless! If you are capable of writing out all of the
details of this user experience in English, you might as well just write them
out in code, and at least then you’ll have a prototype at the end of it that you
can play with and reason about. It’s basically impossible to judge whether a UI
is “good” when you’re just looking at a written English description of it.

The same is true for complex algorithmic product features. For example, if
someone showed you a written description of Google, ChatGPT, or the Instagram
Feed , would you have any idea how “good” the product would be? Of course not.
You can only judge these products by using them and seeing their algorithms at
work.

The same has been true for Yext Chat. The quality of this product relies
ultimately on the quality of the chat bot’s responses, and there is no way to
judge that except by building the product, trying it out, and iterating further.
That’s why we never bothered writing a spec for Yext Chat. The very first thing
we did was build a prototype.

### Understand the Value of Focus

Part of the benefit of the agile methodology is the ability to change priorities
quickly as requirements evolve. This is certainly a good thing because
requirements really do change in the real world. You bring on new customers; you
learn more about what they actually want; the technological landscape evolves.
To meet these challenges, it’s important to be able to pivot quickly and deviate
from your long term plan.

However, this power should be used with great responsibility. Changing
priorities isn’t free. As any engineer will tell you, _context switching_ is a
productivity killer. Every time that an engineer has to switch what they’re
working on, they have to reload a new area of the codebase into their brain, and
it can take a while to hit their stride again. (This may be especially true for
software engineers, but I think it applies to everyone.)

Conversely, as an engineer gets deeper into one section of a codebase and spends
more time thinking about a very specific problem, they gain increasing mastery
over that section of the code and they start to uncover new insights and
generate new ideas about how to make it work even better. This sort of mastery
takes weeks, months, or even years to achieve, and you’ll never get it if you
shift your focus every sprint.

This doesn’t mean you should _never_ change priorities. That’s equally bad, and
it’s why the agile manifesto states implores us to embrace change:

> Welcome changing requirements, even late in development. Agile processes
> harness change for the customer's competitive advantage.

If you never allow requirements to change, you’ll never build something your
customers truly love. But if you shift your priorities each sprint you won’t
either.

### Invest in Developer Productivity

You should invest generously in making your team more productive. Let your team
adopt the latest and greatest technologies, even if it takes some time to adopt
them. Let them build libraries and internal tools that will make their work
easier in the future. Most teams do too little of this, but I’ve almost never
seen a team that does too much.

Although developer tooling doesn’t deliver value directly to the customer, it
controls the _speed_ with which the team can deliver value to the customer,
which is just as important. Consider the simple math. If you spend a month on a
project that will make your developers twice as productive, you may be a month
behind, but you’ll be caught up within another month, and in 6 months you’ll be
5 months ahead of where you would have been.

### Go Fast

In software, speed is the key to _quality_. This may seem counterintuitive. You
might think that by taking your time and building a product slowly, it will turn
out higher quality, with fewer mistakes. But in reality, this is not how
building software works. In software, speed and quality are interrelated.

The reason for this is that building great software requires that you iterate
over and over again, releasing things, seeing what works, and then releasing
more things. Ultimately you’re trying to figure out what actually needs to be
built, and this requires iteration, and iteration requires speed.

This is very different from, say, building a house, or painting a painting. You
don’t get to iterate on a house or a painting. Once it’s done, it’s basically
impossible to change, so you’d better take your time making sure it’s perfect
the first time. But software isn’t this way. Software is constantly evolving,
and you can usually make improvements very easily.

Therefore it behooves you to ship things quickly, because once your software is
shipped you’re actually in the best position to improve it, because you and your
customers can use it and see exactly what needs to be improved.

### Set Deadlines

There are many ways you can increase the pace of work. One way is to impose
deadlines. Deadlines can be a useful tool for motivating the team and increasing
the pace of work. Without deadlines, work can go on endlessly. Without
deadlines, you don’t have to make any hard tradeoffs. Deadlines can have a
galvanizing effect on the team.

However, deadlines should be thought of as a means to an end, not an end in and
of itself. Deadlines are a way to make the team move faster than they would have
otherwise. But for the most part, they’re basically meaningless. Your customers
don’t care about them. So if you find that a deadline is causing your team to
make bad decisions - like shipping software that simply isn’t ready, or causing
people to pull all-nighters - then you should dispense with it.

### Demo Often

Every time a team member ships anything, no matter how small, it should be
accompanied by a brief demo. Demoing often has two benefits. For one, it
improves morale significantly. People love seeing their work come to life.
Conversely, people hate slogging interminably on a project without seeing any
tangible product.

Another benefit is that it allows you to constantly adjust course. As we
discussed already, many products - especially things that involve complex UI
interactions or unpredictable AI models - are impossible to judge in the
abstract. You have to actually play with them and see them in action to know if
what you’ve built is any good.

### Spend Time Working, Not Talking About Work

The ratio of time spent actually working - boots on the ground, hands on
keyboards - to time spent _talking about work_ - in meetings, sprint planning,
on Slack, whatever - should be somewhere in the neighborhood of 90/10. At many
(most?) companies this ratio is inverted. This is crazy. Do not let this happen.

It’s very easy to spend endless amounts of time talking about “ways of working”,
or planning for an upcoming sprint or product launch. Some amount of this is
necessary. If you spend 100% of your time writing code and 0% of your time
coordinating with your teammates, you will very quickly start pulling in
different directions and the project will devolve into a disorganized mess.

However, the much more common failure mode, in my experience, is that teams will
spend the vast majority of their time in meetings coordinating with another,
debating abstract ideas about what needs to be done and how it should get done.
Their work-to-talking-about-work ratio is out of whack.

The antidote to this disease is to shut up and build something. Get in there and
write the code. Even if it doesn’t come out perfectly, you'll actually have
something tangible that you can discuss, instead of discussing things
interminably in the abstract. (This gets back to the _Make Prototypes_
principle - it’s easier to make decisions about real working products than it is
about abstract ideas on paper.)

### Let the Best Ideas Win

This is the most important principle on this list. You must let the best ideas
rise to the top and win, no matter who or where they come from. Too often, the
engineering manager, or product manager, or some executive, is the only one
allowed to come up with ideas. This is bad.

You want a culture where everyone can come up with ideas, and where the ideas
win purely based on merit, not based on who had them. Seniority shouldn’t
matter. Great ideas come from the top, bottom, and middle.

One reason this is important is that finding the best ideas is a game of numbers
and probability. Most ideas aren’t good - even if they come from really smart
people - but a small minority are. So the name of the game is to have a lot of
shots on goal, so to speak. Try out many ideas, accepting that many won’t work,
but that a small percentage will work very well.

Another even more important reason this is important is that people are willing
to work a lot harder on _their_ idea than someone else’s. It’s very demotivating
to feel as if you have no control over what you’re building. But if you feel
like it’s at least partially _your_ invention, you will work harder and make a
better, more beautiful product.


What "Agile" Means to Me

A framework for understanding how to use AI in your business.

The Four Essential AI Use Cases


In my experience building B2B software, I've repeatedly observed that a
philosophy of **open building** tends to create the highest quality, most useful
software. An "open building" approach involves building all software as if it
were top quality, customer-facing software.

Traditionally, when companies build software, they build it very differently
depending on whom it's for, and there are basically three constituents you might
be building for:

1. **Customers:** People who are paying money for your software and keeping your
   business alive. Customers are the most important constituent and generally we
   direct most of our effort toward them. However, in B2B SaaS, the customers
   who actually use the software are sometimes a captive audience. Sometimes
   they have no choice but to use your software because their company may be
   locked into a long contract with you. As a result, quality and usability
   sometimes suffer. But in general, customer-facing software is held to the
   highest standard.
2. **Prospects:** People who are considering buying your software. For
   prospects, the goal is usually to get them into some kind of demand-gen flow
   and get them talking to a salesperson as soon as possible. As a result,
   software built for prospects often optimizes for polish and appearance (i.e.
   flashy landing pages) but usually doesn't offer access to much actual
   functionality.
3. **Employees:** People who work at your company. Employees naturally need
   software do to their jobs. Often these employees are engineers who rely on
   microservices built by other engineers. Though they could also be other types
   of employees - salespeople, marketers, business analysts - who are seeking
   information or tooling to do their job. In this category, usability often
   suffers greatly. If customers aren't going to be using the software, why
   should we invest in making it sleek and intuitive?

Most companies treat these three user personas very differently when building
software. But a **philosophy of open building** demands that they all be treated
essentially the same, because the lines between them are actually surprisingly
blurry, and treating them all as equal and deserving top quality software
actually yields better outcomes for everyone.

To make things more specific, my philosophy of openly building software has four
main tenets:

1. Internal platforms should be built to the standards of customer-facing
   products.
2. Whenever possible, internal microservices should be made into public APIs.
3. Everything should be documented publicly.
4. Products should be free to try out.

Let's go through each to understand why it's important.

## Internal Platforms

Every software company has internal platform teams whose primary customers are
other engineers at the company. A few classic examples of such teams are...

- A UI team that manages a UI component library for other teams to use
- An SRE team that manages CI/CD
- An infrastructure team that manages things like Kubernetes clusters,
  Terraform, etc.
- A data engineering team that manages a data warehouse for other teams to use
- An ML Ops team that manages the training and deployment of ML models

These teams play a critical role in the success of the company. While they don't
deliver software _directly_ to customers, they control the speed, consistency,
and reliability with which the rest of the company can deliver software.

In my experience, the software that these teams deliver tends to be held to a
lower standard of usability than software that is delivered directly to
customers. These teams tend to think less about things like developer
experience, API design, and documentation than teams who are delivering software
directly to customers. After all, these teams are building software for their
colleagues, so it doesn't matter if it's a bit clunky. It's not like a customer
is going to complain about it and cancel their subscription.

I think this is a mistake. I think that internal platforms must be held to the
same standards that external products are. There are two reasons. The first
reason is that almost nothing is more important than making your own employees
efficient. The cost of forcing your employees to use clunky software is every
bit as great as the cost of forcing your customers to use clunky software.

By slowing your employees down and forcing them to use unintuitive APIs or
unreliable services, you are wasting the most valuable resource your company
has: time. One of the most important determinants of success in the software
business is speed - can you ship features faster than your competitors and fast
enough to keep up with your customers' rising expectations?

Every moment your engineers spend dealing with a slow CI/CD pipeline, or writing
their own UI components from scratch, or waiting for a data warehouse query to
run, is a moment they are not spending doing work that actually adds value. As a
leader, this should terrify you every bit as much as bad customer-facing
software.

The second, less obvious reason for holding internal platforms to a high
standard is that many of them can ultimately become new sources of revenue. The
most classic example of this happening is Amazon Web Services. AWS began as an
_internal_ platform meant to save Amazon's own engineers time on tedious,
"undifferentiated heavy-lifting" like provisioning databases, servers, messaging
queues and the like. But it wasn't long before Amazon realized that, if they had
these problems, every other company building software probably did too. Led by
now-CEO Andy Jassy, Amazon made AWS into a public product, and the rest is
history. Today, AWS is a $100 billion business.

At Yext, where I currently work, we recently underwent a similar process with
our [Pages product](https://www.yext.com/platform/pages), which is used to build
SEO-optimized websites for thousands of businesses. Pages was once a
walled-garden, internal platform that only Yext employees could use to build
websites. But increasingly we realized that many of our customers wanted to use
this technology to build websites on their own, or with the help of a
third-party agency. So we opened up our platform and made it into a public
product.

In the process, we not only unlocked a new revenue stream but also dramatically
improved the quality of the product, because we were forced to now hold it to
the standards of an external, customer-facing platform. This meant creating a
more intuitive developer experience, better documentation, and a more
interoperable system built on Vite and React. This dramatically improved
developer experience also made our _own_ team dramatically more productive.

## Make Private Microservices Public APIs

A second, closely related principle is that you should strive to make all
internal microservices into public APIs. I use "internal microservices" as a
very broad term to refer to any piece of software that communicates with other
internal software and/or employees, but not with the outside world. This
includes RPCs that interface with each other as well as admin portals where
internal employees can perform privileged actions that ordinary customers can't.

In a B2B setting, you should be wary of these internal microservices. You should
always ask yourself, "Should we just make this public?". For example, if you've
written a microservice that fetches data and displays it on a table in an admin
portal, why not just make it a public API that returns JSON? Then you can use
that same API to power your admin portal, but your customers can also tap into
it to view the data and build their own dashboard if they want to.

In my experience, this type of programmability and interoperability is crucial
for large enterprise customers. Big enterprises almost always want to do things
programatically, often with complex business logic. If you require them to
manually click around in your platform or manually import and export data, you
will hamper their ability to do their jobs. A good litmus test here is that
everything you can do by clicking around in your platform you should also be
able to do programatically, via API.

Furthermore, making internal microservices into APIs again forces you to hold
your API design to a higher standard. It forces you to think more about the
developer experience for the person using your API. Even if it turns out that
customers don't use an API and only your own employees do, you've still saved
the company a lot of time and effort by making it easy for your own employees to
use.

## Document Everything Publicly

The third tenet of my open building philosophy is that (virtually) everything
about your software should be publicy documented. Public documentation should
include...

- Public, transparent pricing
- A public changelog for your product
- Thorough documentation and guides for all public APIs and SDKs
- A public roadmap for your product
- Transparency into security practices, SOC2, etc.
- A public, open forum for questions and support
- Transparency into your company's technology stack and engineering practices
- Special documentation outlining the behavior of any machine learning systems,
  with a special focus on governance and ethics

In fact, there are very few things that should _not_ be documented publicly.
Public should be the default position for all documentation, and documentation
should only be private if there's a good reason. "Competitive advantage" is
usually _not_ a good reason to keep things private, especially when it comes to
high-tech ML products in a B2B setting. Allowing your customers to understand
and have confidence in your product is much more important than keeping your
intellectual property a secret.

Furthermore, you should strongly consider maintaining both your public and
private documentation in the same system. If some documentation about internal
microservices or company practices needs to be kept private, consider simply
adding an `isPrivate` flag somewhere in your documentation system that hides it
from external users but exposes it to internal employees.

A single source of documentation is dramatically easier to maintain than
separate systems for public and private documentation, and it has the benefit of
making your own employees' lives easier, since they will no longer need to
search between several different systems to find what they're looking for and
can instead use the same, high-quality documentation portal that your customers
use.

The other key benefit of documenting everything publicly is that it forces us to
hold documentation to a higher standard. If customers and prospects might read
it, we tend to make the documentation more polished and thorough.

Even more than that, writing public documentation forces us to scrutinize our
ideas and systems more deeply. If something sounds stupid when you write it
down, and if you'd be embarrassed to have a customer read it, then you should
probably think twice about whether it's a good idea in the first place.

## Make Everything Free to Try

Finally, I believe that all software should be free to try out. This means that
anyone should be able to sign up (ideally using Github or Google) and start
trying out your product without speaking to a salesperson. Ideally, your product
should also come with some amount of free usage, so that a new user can
accomplish something meaningful with it before they spend any money. This is a
key tenet of product-led growth - the idea that customers want to actually use
your product before they ink a deal with you.

The most obvious benefit of making your product free to try is that it generates
demand. Allowing prospects to actually use - and hopefully love - your product
is 1,000x better than any landing page or whitepaper at generating
top-of-the-funnel demand for your product. In the past decade, companies like
Slack and Github have had enormous success with this bottoms-up growth model.
Users have adopted free versions of these products, loved them, and eventually
convinced their companies' IT departments to buy them.

But a subtler, equally important benefit of making your product free to try is
that it forces you to think much more about your product's usability,
information architecture, and overall quality. If you know that your customers
are going to thoroughly vet your product before they sign a big deal with you,
then you are forced to hold your product to a much higher standard. The product
needs to be intuitive, polished, fast to get started with, and utterly bug-free.
Anything less and you could lose the deal.

---

Collectively, these principles amount to a new, more open philosophy for
building software. The common thread uniting these ideas is that, no matter who
you're building software for - whether customers, employees, or prospects - you
should build it with the same high standards of transparency, usability, and
quality. You should be wary of silos - of information or functionality that's
restricted to one set of constituents.

This open approach to building software can offer enormous benefits:

- It makes engineers and other employees more efficient, because the tools they
  have to do their job will be built to the same high standard of quality and
  usability that your customers get.
- It reduces duplicated work. Instead of writing separate internal and external
  documentation, or building external APIs separate from your internal
  microservices, you can simply do things _once_ for both your customers and
  employees.
- It future-proofs your product for evolving customer needs, because your
  product's low-level APIs will already be open and documented, and your
  internal platforms will already be built to the standards of customer-facing
  software, making them easy to package and monetize.
- It will improve the overall quality of your product by bringing more of it
  into the public eye and forcing it to be held to higher standards. (Because
  technical debt grows most easily in the dark, where nobody can see it.)

To some readers, these ideas will seem obvious. Many companies already build
software this way. To others, these ideas will seem controversial or even
dangerous. Some people will consider it a waste of resources to hold every
single internal tool or microservice to the same standard as customer-facing
APIs, or to go through the trouble of documenting everything publicly. Some
people will insist that publicizing their pricing will weaken their ability to
negotiate, or that documenting too much about the product risks giving away the
secret sauce to competitors.

But I believe this thinking is wrong. I believe that the companies who will
succeed in the future will adopt openness and build high quality, transparent,
interoperable software that anybody can use. In the long run, this will make
people's lives easier, improve resilience and trust in our software systems, and
spur a new generation of innovative products.


Principles for building top quality, transparent software.

Max Davish

Blog