Deliver a great developer onboarding experience with sample apps

Documentation is a must have for any piece of technology but if you want a great developer onboarding experience, you’ll also need some sample code. Code snippets are a great start but it’s even better if you can wrap them up conveniently and tell a story with a sample app.

In this post (and this three-minute video), I’ll discuss the value of sample apps and I’ll share some tools and processes that you can put in place so that your community and your Developer Relations (DevRel) team get the most out of it.

For reference, this content is based on the lessons learned from building and sharing our developer-focused Sample Gallery. We started a couple of years ago and grew our collection to eight sample apps that have been used by thousands of developers.

Leverage sample apps as a key DevRel asset

Sample apps are a great asset for DevRel in several ways, some of which may not be obvious at first.

Provide a reference implementation

The first obvious benefit of sample apps is that they provide a convenient way to expose best practices but this goes far beyond code because it also covers software lifecycle management and tooling. For example, we also use our sample apps to present opinionated examples of CI workflows, packaging and release management.

Engage with your community

Open sourcing your sample apps projects brings some additional benefits. If you share your apps on a code collaboration platform like GitHub, you’ll notice that your community will engage with you on this new channel with questions and issues. Over the years, we’ve received great feedback and contributions so I highly recommend it.

Learn about customer pain points

I like to think of sample apps as some mini production-ready projects. The reality is that you, as an advocate, will also benefit from these apps because you’ll learn a lot about the product and in particular about the ways your customers use it daily. This experience is a great way to build empathy, detect friction points and convey feedback to the product teams.

Define a scope for your sample apps

Just like when building a product, you need to start with a design phase in which you’ll establish some sort of specifications or scope for your app. If you just add new features on the fly on a single app, you’ll lose focus and end up building a single massive app. This large app will intimidate new users and you’ll have a hard time to build an engaging storytelling around it.

To prevent that from happening, I recommend that you create a couple of small apps and set up a plan so that they each hold specific features that are clearly tagged.

The approach we’ve taken to address this concern is to create multiple sample apps and split them in two categories:

• Business-oriented apps tell stories that are tied to customer use cases. For example, a retail use case for a fictitious electric bike manufacturer or a customer service experience with a company that rents meeting spaces.
• Recipe apps hold collections of small code snippets that demonstrate code patterns and implementation techniques in isolation. Each recipe covers a specific technical topic like implementing conditional rendering or messaging across web components. Having those snippets within an app is a convenient way to bundle them in a single place and display their output close to the source code. We also use recipes to present how developers can upgrade from a legacy web framework with side by side implementation examples.

Business samples vs recipe samples

Each of these apps have a strong visual identity and theme so that there’s no confusion as to which is which or what story they’re telling.

Deliver a great onboarding experience

Designing and building the apps is only one part of the story. Once your users have installed the apps, you need to onboard them. You can do this with a readme or a video but we’ve found that there’s way more user engagement if the content is interactive and embedded within the app itself and/or within an IDE. This is why our sample apps use both in-app and in-code guidance.

For in-app guidance, we use a Salesforce feature that lets us record introduction tours that guides users around the app with a series of popup dialogs. We use it to present the business use case and highlight key features with links to documentation.

In app-guidance is a feature built-in Salesforce but you can look for alternatives in the platform of your choice. When building tours, keep them concise because analytics indicate that users tend to drop off when there are more than five steps or too much information in each step.

Onboarding

In combination with in-app guidance, we use CodeTour, a Visual Studio Code extension that provides guided tours of the sample app source code within the Visual Studio Code IDE. CodeTour works in a similar way to in-app guidance: it’s a series of configurable popups that we use to present the architecture of our apps and highlight the most important pieces of code.

CodeTour

Expose and promote your apps

Sample apps are of limited value if your community can’t find them so you’ll want to turn them into go to developer resources. Start by building a landing page on your developer website that lists your apps with their descriptions, screenshots and specific features tags. This first step is pretty straightforward but you shouldn’t stop there. To get the most out of your apps you’ll want to cross-reference them in all relevant content as shown in the diagram below:

Content diagram

Closing words

This sample app strategy has proven quite successful for us over the years so I recommend that you give it a try. Building these apps and the associated developer experience requires a lot of work but the investment pays off both in terms of community engagement and in terms internal benefits (advocate skills and empathy, product feedback loop…).

Don’t hesitate to check out our sample gallery for ideas or to chat with us.