Developer Onboarding Best Practices

Hoss@ /

You may have a powerful API, but if you want developers to truly harness its potential, you’ll need to provide a powerful developer experience to go with it. Developers have a cornucopia of tools available to them, so they’ll gravitate towards those that take steps to aid them through implementation.

Delivering a strong developer experience is more than just compiling intensive documentation and support hubs. That being said, they’re great foundational pieces. We’ll be looking at their importance and how Hoss’s developer experience tools can provide them to your developers.

Create robust documentation

A developer’s initial experience begins with your documentation. They’ll look at it to answer questions about what’s possible and to ensure you have everything to support their integration. One of the best ways to help with that first experience is to walk them through to Hello World. Give them a getting started guide and emphasize it in the docs.

What does a helpful getting started guide look like? It covers the basics, and only the basics, in a clear, concise manner. Without this initial step, it’s going to be hard for a developer to reach the larger goal of a deeper integration.Show them what they need to begin making a simple call. This guide is the foundation that developers' experiences with your API is built off of, after all. Only after you introduce them to your API can you hone in on more specific use cases.

Those use cases are best explained with tutorials. Though they spend much of their lives interacting with machines, developers are actually human-beings, after all. Your docs should be written in a way that makes it easy for a person to follow. Make sure you include a narrative to your tutorials, so it’s easy to follow along and understand the mechanisms behind the process. In other words, tutorials should be more than a series of steps: you want to put those steps within the context of the problem that is being solved.

On the surface, a tutorial might seem a lot like a getting started guide. Here’s the difference: Think of the getting started guide as the train station that your developers need to go through to get to their destinations. Everyone getting on a train needs to go through the station, but not everyone is going to the same destination. Likewise, developers will have different goals and use cases for your API. From the getting started guide, they can diverge and follow the tutorial they need for their own use cases.

Another great thing about train stations? The large, impossible-to-miss ticker showing all the destinations. Make it so your tutorials are also impossible to miss. After the getting started guide, show them exactly where they should go for next steps now that they're up and running with your API.

Of course, both the getting started guide and the tutorials you've made are more useful if they contain actual code snippets, ideally in the language a developer already uses. You can take a similar approach with your API reference, which should be complete and accurate. Share example cURL calls, as well as copy-paste language-specific examples for every endpoint.

All of this can seem like a daunting undertaking, because it can be, but some tools can make maintaining your docs a breeze (more on that later). For now, let's look at how docs alone aren't enough and how a strong developer experience needs another essential aspect: community support.

Provide a platform for discussion and support

Your docs may answer most questions, but certainly not all of them. Even the most robust documentation can’t cover every edge case. Some problems just need human support. It's important you provide a place for developers to get that support. It will help more of them get onboarded and keep developers engaged who hit a snag later, as well.

In fact, there are two places we recommend having to offer support to your developers. The first is having a robust online developer community. By having a place to facilitate discussion around your API, your developers will help each other with their problems and grow their collective knowledge of your API.

Even checking in on that community hub can help out developers, because you can bring answers back into your documentation, too. Some confusion regarding an issue plaguing the community? Chime in with a helpful response in the discussion, then note internally how the docs can be adjusted for clarity.

Now that doesn't mean you're off the hook from providing your own dedicated live support. Some problems just aren’t possible for community members to answer. That's where you come in. It's always helpful to offer live support for your developers, especially since you'll be the one to address a developer's most frustrating issues, such as billing and account permissions issues. And no, sticking a phone number at the bottom of your website isn't genuinely offering live support. Developers will seldom call a support number, but a lot will take advantage of a live chat function.

Consider listening for issues outside of your own systems, too. The best developer relations teams are tuned into Twitter, GitHub issues, Stackoverflow, and other places. Developers may ask questions or rant about a problem—and you can be there to provide a helpful answer. Subscribe to alerts or follow keyword searches, then make sure you check and respond accordingly.

Use modern tools to streamline API integration

In addition to docs and support, your product itself can use the same approach to better onboard developers. Guide new developer signups to the tools they need to reach Hello World and beyond. A developer dashboard provides the tools to pull in data relevant to a particular account. For new signups, this will mean suggesting the next step to take the developer closer to success.


For example, new developers often need to create or access API keys. Your dashboard should make those easy to grab and use. Help developers take that next step by embedding it within the dashboard or linking out to your getting started guide. And since those first few calls can sometimes result in errors, your dashboard can help identify (and potentially fix) those problems with a searchable request log.

A great developer experience can improve your onboarding, but it also can be a big project to do right. A typical content management system isn’t enough to hit all of the requirements. Ideally your developer portal and dashboard are user-aware, so they can react to the unique needs of each developer. That’s the idea behind Hoss’ developer experience platform: great documentation, content, analytics, and dashboards in a single product.

The unified knowledge hub gives you a place to contain all your API knowledge in a developer-friendly way. Host your getting started guide, tutorials, and reference. Include code snippets, with fancy, SDK-aware, personalized documentation included.


Okay, now what about maintaining that documentation? That's another benefit of our unified knowledge hub. With it, every change goes through our linter to catch any errors. Spelling mistakes, broken links, and other problems that plague documentation maintenance are taken care of for you.

When you are ready to deliver a superb developer experience, reach out to the Hoss team so we can show you what we’ve built.

Subscribe to Hoss ModeA weekly newsletter with curated articles, community discussions, news and trends.

Webinar: Developer Experience Strategy

Read more
Join Hoss for a webinar exploring developer experience strategy, including tactical tips that any team can implement and important learnings from industry leaders.
Back to blog

Copyright © Hoss Technologies, Inc. 2021 - All rights reserved. Terms of Service & Privacy Policy