The Ad Hoc
Platform Smells Playbook

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.

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.

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.

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.

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?

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.

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]({{’/ato/’ | relative_url}}), 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.

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.

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.

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]({{’/product-field-guide/’ | relative_url}}) 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.