“Platform 1, Taipei City Hall Station (top platform view)” by mailer_diablo, CC BY-SA 3.0

The Fine Line Between Building a Platform and Overengineering

Written by a human, for humans ❤️


I love building platforms. There’s something quite magical about them that I can’t really explain. When done right, a platform can anticipate customer needs, save development costs and even create a wonderful ecosystem around it. But platforms are also fertile territory for overengineering.

Today I would like to analyze and reflect on what makes a good platform. But before, I should stop for a few seconds and define what a platform is in the first place (my past academic-self would not let me live with it if I didn’t).

I’m not going to bother you with dictionary definitions. I like to think of a platform as a software solution that’s half built, but in a good way. Don’t get me wrong, a platform offers you a complete set of functionality, as long as you do your part, which is mostly about configuring it.

To put it in simpler terms we can define these equations:

Non-platform software                   =   functionality
Software Platform   +   configuration   =   functionality

Gmail is a prime example of non-platform software. You register, you get an email account, you log-in and you immediately have an inbox, you can send emails, filter, search, etc. And yes, there is of course certain amount of configuration that you can do within Gmail. Arguably, I’d say it is pretty configurable. But the configuration is not required for it to provide the basic functionality. It is optional, and quite frankly, many users would not even bother touching it, ever.

On the other end of the spectrum, Salesforce is very much a software platform. Once you register on their website, you log in to your workspace and, unless you configure it, you’ll get almost no functionality out of the box. Then starts the process of getting your hands dirty and tweaking the workspace to meet your unique needs. Tutorials, pre-packaged solutions, templates and marketplaces can make this configuration process easier for you. But that doesn’t mean that the configuration is not there, it’s simply managed for you in that case.

So which one is better, a standard software or a software platform? As usual, the answer is pretty nuanced and depends on what you’re trying to build. If the use cases that you’re going after are pretty standardized, building a traditional piece of software with all batteries included should be your go-to pick. But if you’re going after a diverse set of use cases with a lot on inherent variation within them, then being intentional about platform building is quite likely going to give you a better result.

Most of my industry experience has been in building platforms. Particularly enterprise SaaS platforms like Medallia, Salesforce, MuleSoft or Dialpad. It requires a different mentality: you’re not just building a product but rather a whole array of possible products based on how each customer configures it. In my opinion this single difference has ramifications into the whole software development process.

For Product Managers and UX Designers it’s no longer enough to enumerate requirements and mock UX a limited set of screens. They need to think about a diverse set of user personas, put their various requirements into categories, find common denominators and points of variance, and articulate what should be the core feature vs. its configuration space.

For Engineers it’s no longer about building one feature. It is about building an abstraction of it and all of the various flex points in the architecture so that the various configuration options (both current and future) can be accommodated without constant refactors. It’s about putting APIs first, as no platform can be successful without programmatic access for customers and partners. It’s about thinking far into the future and being certain that every single bit of functionality that you expose will have to be maintained until the end of time, or a careful plan for retirement be put in place.

For QA teams it’s no longer enough to test a set of use cases. They have to be aware about how real customers usually configure the platform and create test cases that cover those scenarios. Furthermore, they need to be able to get alerted when new configuration patterns emerge, so they can be prepared to test those too.

For Release and DevOps roles it’s no longer about rolling out a set of changes and go on with life. There will unfortunately always be special tenants (highly regulated or gov environments), data migration or feature deprecation plans that need to be considered. In some cases they will need coordination with customer-facing roles to time risky deployments so they don’t land in the middle of a contract renewal negotiation with a not-so-happy customer.

One of the biggest pitfalls of platforms is the fine line we walk when we build features that no one asked for. It usually goes like this:

  • We’re working on our established e-commerce platform with hundreds of customers ranging from small to big corporate.
  • Our friendly Product Manager puts a meeting in our calendar and starts describing the requirements for a new feature. Some customers want their reports to be emailed to them every morning. He starts enumerating use cases, JIRA tickets and target rollout timelines.
  • The UX Designer has put together a beautiful set of mocks with how these reports will look like when rendered in the email itself.

Now it’s our turn in engineering and we start asking the tough questions:

  1. Why e-mail? Maybe some customers will want these reports sent via WhatsApp, or Slack, …?
  2. What does exactly “every morning” mean? Just business days or every day? What about holidays? In what countries? Is that configurable? And at what exact time? In what timezone? What if the email goes out to a group? Whose timezone do we use?
  3. And what about the email itself? Why just English? How will it work with translations? What if customers want to style it to have their corporate look and feel and logo? And the from: address, isn’t that configurable too? And the email subject of course.
  4. What if today’s report has the same contents as yesterday’s, should we send it too? Or will some customers prefer a diff or even no message at all to be sent?

There are at least 5 toggles and a bunch of templating/styling options that could arise from this simple requirement. And this is all without even getting into the customization of the report itself, and whether it goes as attachment or in the email body, just to name other things.

Ideally, a great Product Manager would have already thought of most of these cases and may even have supporting data about which elements are worth making configurable on launch day, which others to build later and which ones to leave as one-size-fits-all. This is a back-and-forth in which the Product Manager will iterate the requirements and UX designs ideally in tight coordination with Engineering.

And, maybe this is just my experience, but in many cases these configurability discussions will only happen if engineers are involved. It’s not that Product Managers or UX Designers don’t care about it, but we engineers are more used to thinking in abstraction layers and therefore more prone to raising these configuration-must-be-discussed concerns.

To continue our story. We’ve decided to make stick to just email for now, no WhatsApp or other channels. We will make the time and timezone configurable, and we’ll keep it simple with just Monday-to-Friday emails for now. Our Product Manager is happy and says “that’s enough for V1” so we’re tasked with building it.

Here there’s a major fork in the road. We can take those decisions at face value and build exactly that. Or we can anticipate that some of those configuration dimensions will eventually be required from us. We can do this in various ways. For example by making the email contents be an actual template that’s externalized from the code and stored as a separate resource (even if it is the same one shared across all customers). We can make the Monday-to-Friday decision part of an enum set of strategies or, better yet, use a library that is aware of things like holidays and multiple calendar types besides Gregorian. I call these flex points though I’m not entirely sure if that’s a standard term.

But is it worth adding these flex points? There is no right answer here. There are 4 possible scenarios:

  1. We don’t bother adding flex points. Time goes by and no one ever requested any other configurability to be added.
    ✅ This is a major win: we kept the code simple, we didn’t waste time in designing flex points that no one ever cared about.
  2. We don’t bother adding flex points. Time goes by and more and more configuration requirements are added on V2, V3, V4.
    ⚠️ This is a risky path: on every version we need to refactor our code, with the likelihood of breaking things for existing customers.
  3. We decide to build some flex points. Time goes by and no one ever requested any other configurability to be added.
    ⚠️ This is an over-engineered path: our code could be simpler, more testable, easier to debug and even faster to run.
  4. We decide to build some flex points. Time goes by and more and more configuration requirements are added on V2, V3, V4.
    ✅ This is a major win: by anticipating the potential areas that could change, adding those new requirements is in many cases trivial.

My experience has usually been on category 4., though I have to admit having experienced all four of them more than once.

In future entries I’d like to go deeper into how to design and build these flex points. So if this sounds interesting, stay tuned!

Written by a human, for humans ❤️

Comments

Prefer to keep it private? Reply by email.