Making your platform useful to developers

A technology platform can dramatically improve the delivery of government digital services — if developers will actually use it. If they don’t, the platform investment is wasted. But adoption doesn’t just happen. Adoption comes from treating the platform as a product and deliberately creating a good developer experience (DX). That means designing for streamlined onboarding, self service, consistency, and managed complexity.

A technical platform can provide huge benefits, solving common technical problems once, rather than thirty different ways across thirty parts of the technical ecosystem. It can embed compliance and brand standards across applications; it can speed up application teams to ship more quickly. But the best built tools in the world won’t be adopted if developers become frustrated. DX is the difference between success and failure.

Yet, DX is all too often left to chance. Organizations will staff a team of software engineers to build a platform, and assume the engineers will know exactly what to build for other engineers and developers. But assuming that one engineer will intuitively know the needs of all the engineering teams in an organization is like assuming that all runners will be comfortable in the same shoes. Needs, preferences, and styles will differ based on the environment, the type of application they’re building, and the team’s individual working styles. One size does not fit all, and fit matters for developers’ tools just as much as shoe fit matters for a marathoner.

For a platform to be successful, it needs to provide a good DX for its unique developer audience, showing them that using the tooling is easier and better than coding their own solutions. The platform must also address the business constraints and security requirements of your unique organization. In short, your platform needs to be designed like a product.

In the case of a technology platform, that means you must design the platform for your specific needs, and also specifically for streamlined onboarding, self service, consistency, and managed complexity.

Streamlined onboarding

As a team builds out a platform, they often require developer teams to follow manual processes to gain access to the platform tools — what we call onboarding to the platform. While this can make sense for a new, minimally viable product version, manual processes should always be considered highly temporary. They cannot exist in the end state of the platform’s onboarding.

A good experience begins the moment people first interact with your platform. Developers want tools to help them build and deliver value quickly. Creating frictionless onboarding “golden paths” allows for excited, engaged developers, with more successful wide-scale adoption.

Making your platform easy to access is the biggest single step that you can take to ensure your platform’s success. Go out of your way to minimize confusion, cumbersome request and approval processes, and lengthy delays. Streamline the process of getting started, and give a path to learn advanced features. Provide clear and simple documentation with easy “on ramps.” When you test onboarding with real developers, listen closely for pain points, and continue iterating until onboarding is a breeze. Make it easier, so developers can focus on solving critical business problems instead of wrestling with tools.

Recommendations

• Automate the onboarding process for developers wherever possible. Automating onboarding requests and approvals is particularly impactful.
• Provide starter kits and sample applications for developers to quickly get to a small, working “Hello World!” application on your platform.
• Continuously test and refine your onboarding process to ensure it continues to function well.

Self service

Similar to streamlined onboarding, a self-service platform allows developers to accomplish tasks on-demand without needing to depend on human “gates” or manual approval processes during everyday work. Tools should facilitate managing things like file storage, networking, database creation, and deployment pipelines using automated processes rather than conversations with people.

As a note, self-service in this context does not mean that developers must write and manage their own automated tools. In most cases, the platform team will be responsible for this work. However, a successful platform must provide robust self-service options for common workflows that are automated, documented, and reliable. (We’ll discuss documentation in our next post.) An even more advanced platform might offer reusable patterns and templates that developers can use to create new automated workflows.

Designing your platform to be self-service takes additional effort. However, that work promotes developer autonomy, which leads to dramatically better code and problem-solving. When developers can effectively set up the environments, applications, and integrations they need, they can do their best work without needless friction and delays.

Recommendations

Create a fully self-service experience for developers on your platform:

• Provide tools and services that developers can use “on demand” without external approval or support.
• Develop easy-to-use interfaces that allow developers to manage applications and integrations directly.
• Set up common workflows that reduce the overall time it takes for developers to ship valuable software to end users (ie, production).
• For even better gains, automate routine tasks to boost productivity, and offer patterns and templates that allow developers to do the same.

Consistency

A good DX decreases developers’ cognitive load, and is thus easy to use. That does not necessarily mean uncomplex (we will discuss managing complexity later), but it does mean consistent.

Good design for developers means abiding by the “principle of least astonishment.” In simple language, everyone building tools for the platform should do so with a consistent vocabulary and design, regardless of module or section. In fact, a developer should be able to interact with a new piece of your platform intuitively based on how the last piece behaved.

In practical terms, this has a few implications. The larger your platform tooling becomes, the more important standardization and repeated conventions become.

Recommendations

Create a consistent vocabulary and design for platform tooling:

• Ensure that platform services and APIs conform to current industry standards.
• Develop API design guidelines, consistent naming conventions, data exchange formats, and response and error message conventions.
• Use common languages, architectural frameworks, libraries, and protocols so developers are building from a familiar starting place.
• Standardize terminology throughout documentation, interfaces, and code.

Managed complexity

Unlike many other customer bases, developers are unafraid of complexity. They routinely navigate and explore complex systems at varying degrees of detail. Platforms should aim to provide a simplified experience for developers while empowering them to explore things running “behind the scenes.”

A well-designed platform experience enables developers to decide what level of detail or abstraction suits their needs. This doesn’t mean hiding or obfuscating important information. It does mean removing irrelevant details. Striking the balance between the two takes thought and effort. Platforms should present information in a way that allows developers to move smoothly “up and down” multiple levels of abstraction. They should be able to inspect the underlying code based on their needs, their role, area of focus, or domain-specific expertise. Consider concealing lower-level systems or infrastructure components that developers don’t need to manage directly. Deeper-level details can be revealed through UI dialog screens or capabilities designed for power users.

Recommendations

• Provide high-level information and overviews that describe the big picture “at-a-glance.”
• Provide additional, detailed materials on the platform as needed, such as architecture diagrams, solution design documents, and comprehensive manuals that detail the inner workings of the tools and systems developers interact with.
• Design simplified interfaces for developers to interact with more complex systems, such as
  • Web-based forms that trigger behind-the-scenes automation.
  • Portals, consoles, or other graphical user interfaces (GUIs).
  • Command-line interfaces (CLIs).
  • Application Programming Interfaces (APIs).

Success comes from ease of use

At Ad Hoc, we’ve supported agencies through every stage of platform build-out, adoption, and maturity. We’ve seen agencies who design good developer experiences get better outcomes from their platforms than those that don’t.

When you treat your platform like a product, you design it to meet the specific needs of your developer. By creating consistency, self-service paths, streamlined onboarding, and managed complexity, you make it easy to use — ensuring your developers will adopt and advocate for your platform. You ensure your platform has long-lasting impact, and delivers your most important mission goals.

To do that, you need to make sure that your developers understand what the platform has to offer, and can find it easily. Tune in for our next post to find out how.