The Ad Hoc
Platform Smells Playbook

Illustration of three layers of paper with icons of a computer, crane, clipboard, and trash can emanating from the layers.

This guide is for owners of technology platforms in government digital services. It describes common platform issues, their causes, and how to clean them up for better performance. To get more out of your existing platform, read on.

Over the past decade or so, the tech industry has made a significant investment in platforms, following the promise of everything from faster delivery to increased security. Government agencies have followed — and sometimes led — the charge, and platforms have become a key tool for agencies looking for better ways to deploy effective digital services to the public quickly and securely.

Here at Ad Hoc, we've written a lot about the virtues of platforms, and how they can help you deliver value more quickly, accelerate the ATO process, and build trust with users. We've helped build large-scale platforms with our government partners, and we've seen them provide benefits to the agencies that use them. We believe in platforms.

And if you're reading this, you likely do, too. You may be running a platform of your own, and have a significant investment in its success.

But while it might be easy to think platforms will solve all your problems, including brightening your teeth, shaving strokes off your golf game, and giving you thicker, more luxuriant hair, what happens when they don't? What happens when the industry's glowing promises don't match up with what you're seeing with your own platform? What can you do about it?

If you can catch issues early, you can reduce their impact and increase the value of your investment into building platforms that serve people well.

In this guide, we'll identify some of the key indicators that you can use to diagnose underlying problems that might be affecting your platform. We'll identify ways to recognize the “smell” of a potential issue and use it to uncover what the real problem is. Most importantly, we'll help you see how to make needed changes to build a stronger platform and provide better digital services to the people your agency serves.

A technology platform can dramatically enhance an agency's ability to deliver successful digital services, but it can also be a large investment of time, effort, and money.

Your nose knows

“If something smells bad in the basement, it will eventually make its way to the attic.”

—Anthony Liccione

The first sign of a platform problem is often a nagging sense that something is wrong. Sometimes, platform owners will ignore that sense for weeks or months, because they're not quite able to put their finger on the issue. There's just a subtle sense of something that seems not quite right.

The concept of a code smell comes from agile software development, and is used to refer to a characteristic of software code that may indicate a deeper problem in need of correction. This same idea can be applied to a platform. Just like a code smell, or that whiff you get when something has been left too long in the fridge, the longer the platform smell is ignored, the worse the underlying situation may get.

If you think you smell something “off” in your platform, trust yourself and take action. Your nose knows, even if you haven't fully diagnosed the underlying issue just yet. We'll discuss specific smells that are common to platforms in government digital services, but these are only the most common smells. Regardless of your situation, pay attention to your nose, and use it to identify the root cause.

Once you recognize a fundamental issue causing a platform smell, you can adjust parts of your platform strategy to make the overall approach more successful.

The Smells

“When you smell something, say something.”

—Jon Stewart

In the following sections, we'll discuss ten common smells that tend to show up in modern technology platforms. These are not the only possible smells, but they're some common ones we've seen. For each, we've included a description of the smell and how to recognize it. We discuss the most common root causes and highlight ways to address the issue that we have seen work in practice.

Each section contains the following structure:

Platform smell: Platform smells are an indicator that something may not be right. You can use them to figure out the underlying issue that is impacting the performance of your platform.

What it means: When you become aware of a platform smell, you can start to dig in and more fully understand what is causing it. Before we can take steps to address a problem, and remove a platform smell, we need to understand what is causing it. Then we can take steps to successfully mitigate the problem.

Clean-up strategies: Once you have a sense of what the underlying issue is affecting your platform, you can take the proper steps to address it. You can address the smell of smoke in your kitchen by opening a window or by turning off the stove. Both of these options will dissipate the smell, but only one fixes the underlying problem.

If you're new to platforms and would like to learn more about what they are and the benefits they offer, we've written a variety of articles that provide more information.


It takes developers a long time to get to “Hello, World!”

Mature platforms have a short path to get users to their first “Hello, World!”, meaning that developers can quickly get up and running with a basic application with minimal (or even no) human intervention. If the time to first “Hello, World!” on a platform is long, it usually means that startup tasks like account creation and resource provisioning require manual intervention of some kind. This friction compounds over time, forcing the platform team to wrestle with manual tasks from an ever-growing backlog of product teams struggling to get started.

Mature platforms automate the account creation process, and let developers self-provision the resources they need to deploy a basic application. Sometimes platform operators will task the team doing manual onboarding with automating their manual steps, using the logic that this team will have the clearest sense of the steps that need to be automated. Bear in mind, however, that if the group charged with manual onboarding is also the group charged with automating onboarding steps, they may face challenges in supporting both sets of tasks unless sufficiently resourced.

Clean-up strategies:

  • Look for opportunities to improve developer onboarding documentation. One way to do this is to look for questions that are repeatedly asked by different users, and ensure that these onboarding steps are clearly documented.
  • Where possible, replace live orientation or training sessions with recorded sessions. This makes it more convenient for platform users to review these sessions at their convenience, and takes the burden of repeating the same information over multiple sessions off of platform staff.
  • Look for opportunities to automate onboarding steps and highlight those that have the largest potential return on platform staff time saved.
  • Ensure onboarding automation efforts are adequately staffed and funded.
Return to top ⇧

Simple things don’t seem to be getting done

It’s happened to too many platform owners: one day you wake up and some simple, routine task that the platform was supposed to magically wave away didn’t get done. To add insult to injury, it always seems to be the most mundane tasks — things like the release not getting properly tagged, or dependencies not getting updated, or a certificate expiring.

Platforms are supposed to relieve product teams of everyday operational tasks so these teams can focus on the functionality unique to their applications. So how does this happen?

If operational issues — things that relate to how the platform is operated and maintained — begin to affect product teams, this very often signifies a deeper issue. It usually indicates a lack of clear ownership. You need to ensure everyone knows the key services the platform provides, the routine tasks needed to keep those services operational, and who is responsible for each.

For every key service the platform offers, it should be clear both internally and externally which platform team is responsible for managing that key service and ensuring uptime. If you can automate away routine operational tasks, great! You should still be sure you know which team(s) own the automation.

And if for some reason you can’t automate it away, be doubly sure you — and everyone else — knows who owns those tasks. There’s no reason your platform should suffer over the routine, mundane tasks.

Clean-up strategies:

  • Documentation and mapping of key responsibilities. Just as your platform has documentation for users, it should also have clear documentation for platform operators and stakeholders listing out the operational tasks that need to be completed, an indication of who completes them, and when they need to get done.
  • A process for triaging and resolving operational issues that surface into view of the platform customers. If an unhandled operational issue does surface, having a process for analyzing what happened and why it happened is important. The end result of this process may be something like a runbook or other documentation that platform operators use going forward to ensure the issue is handled properly.
  • Automate and standardize routine processes wherever possible.
Return to top ⇧

Features are getting orphaned

In this scenario, you get a whiff of things not getting done, and you start to suspect why. Some team in the past built some amazing feature or functionality, and users adopted it. Over time, as things moved around and teams changed, that piece of functionality was left behind. Now, no one has ownership of the feature. This happens as platforms mature and inevitably re-organize.

It also makes sense to be aware of the smell of features that have been orphaned because no one is using them. Perhaps the feature seemed like a great addition to the platform at one point, but time has moved on. This may also indicate that platform teams are focusing on features that are not in demand from platform users.

Clean-up strategies:

  • Much like the previous smell, this is typically a deficiency of platform ownership and governance. You should have a clear understanding and mapping of platform features and who is responsible for them.
  • Regular review of platform features and ownership, including plans to deprecate and remove features that should no longer be part of the platform.
  • Implement a product operations plan.
Return to top ⇧

Application development on a platform takes a long time

Once users get access to your platform and are able to get a basic application running, they will begin developing and testing their application. As they do this, they will take steps to ensure that it works as expected and also to get input and approval from users and stakeholders.

Mature platforms have comprehensive, up-to-date, and helpful documentation for developers, enabling them to understand the features of an application and how they can use them to design and build their application. Feature and API usage will be clear. Many will have example applications and code samples developers can adapt. Mature platforms also provide pathways for users to ask questions and robust support for users to get help when they need it. All of these practices are part of what accelerates application development in a platform environment.

If you are noticing that applications being built on the platform, on average, seem to take longer (independent of the number of features involved), and experience more periods of being blocked than you expect, then some or all of these resources might be missing.

Clean-up strategies:

  • Enhance and/or expand platform documentation. A good approach to doing this can be to look for the areas of the process where users seem to be getting stuck and make sure the steps covering that part of the process are clearly documented.
  • Clarify channels of communication with the support team. Make sure your users know how to reach support when they need it.
  • Review support requests or inquiries to your platform team from users for patterns on the types of things that customers are looking for.
Return to top ⇧

Big platform initiatives aren’t getting done

Sometimes big chunks of the platform roadmap just stall out, and overall platform improvement velocity slows to a crawl. This work might be a migration of the underlying technology, or a big feature roll-out, or any number of other things. Once you’ve ruled out external factors blocking the work, it’s time to look at the internal factors which might be slowing things down.

A slow down might indicate a lack of buy-in for the initiative, either within the platform team or among platform users. It could indicate the platform product roadmap is out-of-sync with user needs. It may also be worth questioning how critical the need really is. If something is deemed highly important, people tend to find a way to get it done.

Clean-up strategies:

  • Take steps to clear recurring blockers, like a consistently failing system that slows down the implementation team’s velocity.
  • Talk to the implementation team. What do they think is slowing them down? How can you help them clear those blockers?
  • Ensure the team has a clear roadmap and isn’t drowning in one-off requests
  • Ensure stakeholder and team alignment. Is the new initiative still desired?
Return to top ⇧

Customers are duplicating platform functionality

You’ve spent a lot of time and money ensuring your platform offers the features your users have asked for. Then, you look around and realize some users have duplicated those same features themselves. Why would they do that? You’re already offering it to them with your platform!

Application teams don’t want to spend the time and energy recreating existing functionality. If they’re doing it — if they are duplicating functionality that should be available from the platform itself such as logging, observability tooling, or support services — this may indicate several things.

First, application teams may feel that your platform needs to support certain features more fully. You offer a feature, but your specific implementation may not meet their needs. Or, perhaps your implementation doesn’t conform to their application stack. There are lots of ways to implement a feature, and some are more intrusive than others.

Alternately, maybe the teams didn’t know your platform supports the feature. Maybe you need to communicate with your users more clearly. Make sure your platform has a clear communications plan for feature availability and support, and make it easily findable — both internally, for your platform operation teams, and also for application teams using your platform.

To effectively meet the needs of your application teams, you’ve got to talk to them and listen to their needs.

Clean-up strategies:

  • Clearly communicate the availability of shared features that your customers may be unaware of.
  • Review support requests. Look for patterns in the types of things users want. Identify requests that indicate a platform feature or tool should be adopted.
  • Talk to platform users directly to get a sense of the kinds of tools and features they are interested in.
Return to top ⇧

Getting final approval to deploy a new application is time-consuming and difficult

Sometimes you have application teams that have gone through all the work to onboard to your platform. They’re bought in. They’ve invested. They’ve done the work. And then they can’t seem to get to that final step and deploy on your platform. That’s a problem.

Before an application can be deployed to production, it is common for one or more different approvals to be required. Applications usually require an ATO, which will involve documenting different security controls for an Authorizing Official. There may also be requirements for approving the content in public-facing web applications and ensuring that it meets other standards, like those for accessibility.

Mature platforms enable a separation of responsibilities so that approvals become easier for the application team than they would otherwise be. If this is not happening, it usually comes back to where the division of responsibility between the teams has been set.

Platform governance is a balancing act. Platforms can be a way to enable development teams by removing operational items that an application needs to run (such as cloud hosting) that are incidental to how a user interacts with a service. Platforms can also be used as a way to enforce standards for things like security, accessibility, and content readability. How this balance is struck can impact how quickly an application on the platform gets approved for production release.

If the governance balance for a platform is struck more in the favor of enforcement — an application can not be deployed on the platform unless it has met specific requirements and standards — then the process will be slower than if the division of responsibility puts the burden of compliance on the development team.

Different platforms will divide responsibilities between platform and product teams differently. How this division is split can impact how quickly applications can get the approvals they need to run in production.

Clean-up strategies:

  • Continuous ATO, where possible; OR Provide a list of implemented security controls that can be directly inherited by customers, and artifacts they can use for security review and ATO.
  • Provide a production deployment checklist to users.
  • Automate as many reviews as possible, and limit meetings and checkpoints prior to production deployment to only those items that require a manual review.
  • Provide visibility into the approval process, so that customers can determine what state their request for approval is in.
Return to top ⇧

Platform adoption has slowed to a crawl

Slow adoption could be due to challenging onboarding or a lack of documentation, but it may also be indicative of a platform that is too rigid and inflexible.

The paradox of platforms is this: they are most effective — providing the most consistency, predictability, rapid development, and rapid deployment — when they are highly opinionated. But those same opinions can also be a barrier to some teams adopting the platform, especially when they’ve got their own ideas of how to get things done. If developers are constantly fighting with the platform, some won’t want to use it. Others will want strong opinions. At the end of the day, understanding what problems your platform is helping development teams solve is critical. If your platform doesn’t make the work of these teams easier, adoption will always be a challenge.

Clean-up strategies:

  • Keep clear documentation of the thinking and rationale behind the platform opinions and architectural decisions. It’s important to let customers know where they have choices and flexibility and where policies are firmly fixed – and why they’re firmly fixed.
  • Keep platform services loosely coupled, allowing a more a la carte approach where possible. If a consumer wants 80% of the platform but has their own opinions about how to achieve an objective, allow for that. 80% is still better than no adoption at all.
Return to top ⇧

Demand for customer support outstrips supply

Once an application is approved and deployed to production, platform users will maintain and (hopefully) enhance it regularly based on the experience and feedback of people using their solution. To do this, they will require information and tooling. They will need visibility into their application and how it is behaving, and data on how users are interacting with it. To the extent that they don’t have access to this information, this may place stress on customer support channels as they attempt to answer overwhelming user questions one by one.

Mature platforms enable users to efficiently develop and deploy applications. A good software development process assumes that product teams are able to access support channels when they encounter problems or need guidance from the platform team on a feature or bit of functionality. When support requests begin to pile up, when time to resolve customer issues begins to climb, or when users actively look for ways to work around support, this may indicate some more fundamental issues.

Additionally, as a platform grows in adoption there can be stress placed on a customer support team simply because that team is dealing with an increasing volume of requests. Mature platforms have dedicated support teams, and mechanisms for routing common questions into platform documentation. They also route common problems into product backlogs so that new features can be released to resolve shared problems.

Effective support teams may take different forms: You could have a large support team, or decide on a small core support communications team supplemented by a rotation of engineers from other teams. However, if you’re relying on a team to both build new features and provide customer support, they will likely be unable to do both effectively.

Clean-up strategies:

  • Make sure you have a dedicated and fully staffed support team.
  • Support your support team. Offer clear, easy-to-use documentation to end users, and be sure it’s easily findable.
  • Track your most common support requests. Look for ways to resolve them permanently through automation or by removing the problem.
  • Provide tooling that enables platform users to resolve issues themselves where appropriate.
  • Recognize that as your platform adoption grows, your support team will need to grow to meet the larger demand. Staff accordingly.
  • Provide ways for your platform users to suggest updates or enhancements to your documentation.
Return to top ⇧

All the smells linger

If you’re picking up more than one of the above smells, or the smell keeps returning, it may indicate you need a better product management structure.

Good product managers — and good product management overall — will help you resolve a lot of smells just by their presence. They’ll help you structure your backlog to best meet the needs of your customers. They’ll help resolve feature ownership questions so critical things don’t get dropped. Most of all, they’ll help you better align your platform with the needs of your end users. Platforms that listen to and respond to the needs of their users are vastly more effective.

Platforms are a product, and just like any other product, they deserve dedicated resources and clear team structure to succeed. Good product management finds those resources, and decides what gets deprioritized while the platform smell is dealt with. It also helps bridge the gap between common problems platform users deal with and the next feature build.

Having a clear division of responsibility and solid product management structures will help you avoid many of the issues platforms can run into. If you do nothing else in response to a smell, do this.

Clean-up strategies:

  • Implement a product operations plan.
  • Make sure each toolset or product area is owned by a team that is staffed with a strong product manager and that the team is also empowered by product-minded stakeholders.
  • Employ a product portfolio approach to your platform products to ensure teams are able to connect dots and manage dependencies across your platform.
  • Make sure you have mechanisms in place to listen to your users, and to have them communicate with you about what they like and dislike about your platform. Sending out surveys is great, but they are not a replacement for having direct conversations with the people using your platform. Build the relationship with your platform users.
  • Mine other sources of information too — log files, support tickets, and feature requests can all help enhance your intelligence on what users want and need.
Return to top ⇧

Hygiene advice

“When solving problems, dig at the roots instead of just hacking at the leaves.”

—Anthony J. D’Angelo

It may sound obvious, but it's worth repeating: platform smells are not the problems you need to solve. They're indicators of a problem, just like a smell in your refrigerator is telling you it's time to take out last week's leftovers. You can cover up the smell, but it will come back unless you take care of the real problem.

Find the source of the smell early

The earlier you listen to your nose, the earlier you can track down your platform smell and the easier the problem causing it becomes to address. Find the root cause, and act early. Better to do that than to have all velocity stop while you fix an issue that has become untenable. Early is easier.

Dedicate what you need to get it done

As you recognize platform problems, the natural instinct will be to simply add them to the backlog. Don't. Fixing these smells will always take secondary priority behind the newest feature, especially when the full team may not recognize the larger problem you're trying to fix.

Instead, ensure you've allocated the necessary time, people, and space to fix the smell. It may slow down your feature delivery temporarily, but will pay off over time with a stronger, faster platform overall. A lack of dedicated resources will, over time, cause issues with the platform and prevent any fix from happening.

Can you stand up a new team? Can you find the capacity in another way, even if that means deliberately not doing something else? Make the hard decisions, and have the hard conversations with stakeholders so that the issue gets addressed properly.


No matter how well you've cleaned out your fridge, you will eventually have to clean it again. Getting the most out of your platform is the same. It will require steady effort and regular smell tests, as well as a particular focus on preventive maintenance now and again. But because platforms enable other development, resources spent here will pay off several times over.

Remember, trust your nose.

Ad Hoc is a technology company specializing in government digital services. We support every stage of the government technology platform journey, from forming a vision that can work for your agency to architecting a robust infrastructure that supports hundreds of apps and many thousands of daily visitors. Let's talk about how we can help you. Start the conversation at

Platform Smells webinar

Want to learn more about Platform Smells? Get access to a webinar recording with Ad Hoc platform experts Mark Headd and Kendra Skeene.

Get access to the recording

Put this playbook into practice.

Work with Ad Hoc to take the next step in becoming an agency that is excellent at building, deploying, and scaling digital services.

Talk to the team