In part 1 of our posts on downstream DX (Developer eXperience) we wrote that reducing API friction is an essential role of developer portals and should be on your task list if you are aiming for a great developer experience. To illustrate this, we listed some tips and tricks on how to eliminate friction & improve DX along the 6 stages of the downstream developer journey.

In this part we will explore how developer marketing techniques can help engagement and improve DX along the downstream developer journey; and how this can generate a viral loop — i.e. the process in which your acquired users turn into API advocates and then in turn help drive adoption of your APIs.

Viral loop steps

The viral loop is a start-up community and e-commerce concept. Simplified, it includes the following steps:

  1. New people start to use a product,
  2. some of them recommend this product to their peers,
  3. even more people start to use your product (= the step that makes the viral loop happen).

In a viral loop users drive adoption, which results in viral growth of your product. If your viral coefficient is higher than one, you will have free growth.

User engagement

All 4 developer experience domains – user acquisition, conversion, retention, and engagement – play a major role in the 3 stages of this viral loop. User engagement is about inspiring your developers, and captivating them to become an involved user. In other words: user engagement is crucial to trigger a viral loop on your developer portal.

Intrinsic and extrinsic motivation

To engage users you need to trigger their motivation to work with/around your product. Psychologists make a distinction between intrinsic and extrinsic motivation.

“While intrinsic motivation refers to doing something because it is inherently interesting or enjoyable, extrinsic motivation refers to doing something because it leads to a separable outcome. Common extrinsic motivations are rewards (e.g. money or grades).” (Wikipedia)

It is important that you take care of both motivation types to be able to involve all of your users: developers can have different reasons for using your product (think work or hobby) and can enjoy their work differently.

How can you motivate your users in practice?

Developer marketing practices

Developers hate marketing, traditional marketing lingo that is. But marketing practices that take the developer approach (e.g. avoid hollow words, include solutions that help users to advance with the tasks at hand) can indeed have a positive effect on your users. Furthermore, developer marketing practices can help to improve the overall developer experience.

How can developer marketing motivate users both intrinsically and extrinsically?

The role of the user journey in the viral loop

The developers that use your APIs are a heterogenous group of users. Developers can start working with your API for different reasons (e.g. programming for work, programming as a hobby), they can have various skills (e.g. preference for specific programming languages, frameworks, and libraries), and have different background knowledge (think users with a wide range of experience levels). Furthermore, their learning strategy — when diving into the API — can differ (code-oriented and concept-oriented learners each tend to look for different resources). A great developer portal answers all possible individual expectations. To do that, it is important that you captivate your users along their developer journey and its stages (the moments between meeting something for the first time and reaching an end goal).

The following is an overview of the main questions that consumer developers will want to find an answer to along the developer journey stages:

The downstream developer journey stages and main questions to answer.



To enable a viral loop and drive adoption, it is important to:

  • Draw the attention of your developers along the whole developer journey,
  • allow developers to enter at any stage of the developer journey, and
  • make sure developers can advance smoothly towards the next stage in the developer journey.

Make it easy and worth it for developers to mobilize their peers and drive more people to visit your portal and use your APIs. Praising something to your peers is a risk you take with their opinion of you. Trust and an excellent experience are prerequisites to recommending something.

Depiction of the relationship between the viral loop steps, the developer experience domains and the downstream developer journey stages.



What developer marketing practices can help to inspire your users along their journey?

Developer marketing practices along the developer journey

Stage 1. Discover & Research

Landing pages

A great developer portal landing page serves all possible user expectations and allows quick and easy navigation throughout its content. The landing page offers the possibility to enter at any stage of the developer journey (e.g. depending on previous experience or learning approaches), and its structure allows to direct or redirect users. Its focus can differ based on the organization’s strategic business goals and user needs, with e.g. an emphasis on products, services, user types, documentation types, thematic areas etc.

Example of an API products/services focused Amazon landing page



The Instagram Platform API landing page forks the user journey into “Learn more” (linking to the business blog) and “Start building” (linking to the API documentation).



CenturyLink’s developer portal overview page first lists blog posts.



Other practices at the discover & research stage

In the discover & research phase it is important to show you have solutions for specific problems and to allow users to get familiar with what the API is capable of.

The Erste Bank API catalog can help your users to browse through the available options. Provide short descriptions to help users decide which API they need.



Use cases can reflect the API’s purpose and showcase interesting implementations. They can help developers to decide if the given API can provide a good solution for their task at hand.

Thematic areas or use cases help to discover what Twitter’s API is about.



Twilio features usage scenarios that show the possibilities of their products on their blog. The use case also illustrates that the company promotes out-of-the-box thinking.



While a search function might be used to hide poor navigation, it can also help to get a very specific morsel of information fast.

Shopify’s “documentation search” function takes a central place on the overview page.



Another solution to immerse users is to target specific niches of the audience directly, for example:

  • a wide range of programming languages to start implementing with,
  • a regional focus where one can choose documentation in their mother tongue.

Stage 2. Evaluate

You already introduced the possibilities you offer, so now visiting developers will want to test your products or know more about specific solutions. Reduce barriers to engage users to get to know the API, include e.g.

  • demos,
  • mock APIs,
  • a test account,
  • samples,
  • try it out (playground) sections,
  • a sandbox environment to test the API without having to reveal personal data. (Sandboxes are essential on developer portals that deal with financial information.)

Marvel has an interactive API tester.



Example of samples that demonstrate how to use xyz on the Google developer portal. Developers can select the technology and language category. The actual samples are stored on GitHub.



Dwolla provides a sandbox environment to allow users to test an API without exposing personal data.



Example of a demo in the Mailjet API documentation



If you need registration and API key/token provisioning, make it as fast and easy as possible. You could include a timeline and/or a nice visual rundown of the whole authentication/authorization process.

When you register on the ABN Amro developer portal you get an overview of all steps that are needed to start implementing (on the right).



Stage 3. Get started

An uncomplicated onboarding process that makes product testing painless will make it more enticing for developers to actually get started with your API. Once the dev's (preliminary) decision is made to use the very API, we need to move towards solving the user-specific case. Some developers will jump straight to the hardcore references, but others will need more contextual information and inspiration.

Well-structured onboarding tutorials, worked examples, how-to and quickstart guides and conceptual documentation (explaining the domain-specific vocabulary) can show how to start implementing.

Make it easy for users to suggest changes in the documentation. This will improve your docs and even increase engagement, since any contribution, no matter how small can result in further affinity for your APIs through a feeling of ownership and a drive for internal consistency. Think of the IKEA-effect.

Rapid API asks users for feedback and suggestions.



SDKs (Software Development Kits) are a good way to jumpstart, especially when you concentrate on distinct key communities and explain how to use the API inside of their unique niches and ecosystems.

Starling Bank provides starter kits that link to GitHub.



Community SDKs, created by external developers are to be celebrated and embraced. It is a sign of your care and involvement with your own users if you publish and monitor their SDKs on your portal. This practice can also keep you on track with what is being recommended by search engines to your new users.

Keen IO’s community SDKs with repositories on GitHub.



Stage 4. Develop & Troubleshoot

Once the developers get to code and implement your amazing API into their creation, it is imperative not to leave them alone: give all the opportunities you can think of for a fallback on community. The hive mind is always smarter, and there is almost no way your company can think of all the possible niche questions and implementations that may arise.

  • Provide a community section or forum and third-party community pages (like GitHub) where developers can communicate with peers and solve problems.
  • Have open-source projects that users can take part in.
  • Enable other communication tools: you can organize meetups, provide a Slack channel to discuss specific cases.
  • Ask for feedback, e.g. on FAQ pages and Knowledge Base pages, encourage edit suggestions if you can.
  • Provide the reference documentation with a section where users can leave comments.
  • To make users enthusiastic about coding around your APIs, you could organize hackathons or online coding competitions.

Spotify organizes hackathons and events for their users.



Stage 5. Celebrate

Celebration is key in the process to engage users and help them become your developer portal advocates.

Give developers a reason to share and recommend your API. We already mentioned Twilio, where users with interesting API integrations receive attention. But also think about non-technical ways you could help developers succeed.

DigitalOcean celebrates active users on their community page.



Another way to help implementations gain visibility is to ask for a guest blog posts — if you have a blog.

Make a virtue out of necessity: if you need to enlist outsiders to make your documentation better or more specific, you could entice your active developer users to contribute (e.g. by paying them).

Rewarding peers: Apigee users can vote on posts.



Stage 6. Maintain

Make it clear what a developer will need to do to maintain an API implementation. Release notes and/or a status page is the least you can do, and any critical changes will have to reach your users asap. Encourage users with different goals by providing different versions of the same information (e.g. detail vs overview).

LinkedIn lists policies with short summaries and full version side-by-side.



Additionally, you could involve your users by asking them to report possible errors and give feedback on your organization’s terms of use and policies.

Motivate, Engage, Involve

When necessary documentation parts are missing or difficult to find then even your most galvanized users will have a hard time implementing and they get frustrated. Think about a combination of developer marketing techniques that both fit your organization’s strategic goals and address your primary stakeholders well.

Pronovix organizes information architecture & UX/DX workshops. Contact us for more details!

This post was co-written by Kristof Van Tomme, who recently talked about developer experience in relation to documentation at the Write the Docs meetup in Amsterdam. Read more: When docs become DX. Many thanks to Laura Vass for the editing!

Other posts in this series:



About the author

Kathleen De Roo

Technical Writer & Information Architect

As a technical writer and member of the Pronovix content team, Kathleen is responsible for writing, reviewing and editing website copy and blog posts, mainly on developer portal documentation aspects. She is currently also diving into the world of information architecture.

She holds master's degrees in history and in archival science & records management.