Different stakeholders interact with a developer portal throughout an API’s lifecycle. In this post I’ll list 8 stakeholders and explain what they need to do their jobs.
1. API developers
Developer teams that build APIs often also end up designing its developer portals. This is often done almost as an afterthought without properly considering all the stakeholders that will need to interact with a developer portal.
Developers typically care most about the ability to deploy documentation automatically as part of the development process, and might forget that other, less technically people, will also need to interact with the site.
From a continuous integration perspective it very attractive to build a static site as part of the deployment infrastructure. But from the moment that portal stakeholders will demand slightly more complex requirements (like access restriction for your docs or conditional text for code samples), your API developers will spend a lot of time, over and over again, building custom solutions for a problem space they don’t fully understand. Company developers will learn how to balance the needs of all the stakeholders with a developer portal that is usable and that serves your business needs, but only after going through a time-consuming learning process that can introduce a lot of technical debt.
To speed up the procedure, we believe it is better to work with a dedicated team member, or - shameless plug - a developer portal specialist like Pronovix, especially when your API team doesn’t have sufficient web and documentation tooling experience.
2. API consumers (developers of the API client and end-consumers)
APIs have two types of customers:
- the developers that build on top of an API,
- the actual API end-consumers that use the service that embeds the API.
Both types of customers need to get value out of your API product. But to get a chance to offer that value as a technology company, developer experience is of primary importance: developers often decide what API they will use, so they act as a decision gate: if you fail to offer them a good experience, they will often not use your API, regardless of its downstream value for end-consumers. End-consumers are typically one step removed from the decision process and do not directly influence API selection. They might even end up paying a premium because their interests are not perfectly aligned with the interests of developers.
This agency problem explains why it is dangerous for technology companies to ignore the developer experience of their developer portals.
3. Product owners
APIs should be treated as products, not as projects. Projects are too ephemeral to provide the continuity API consumers need. Product owners are the stakeholders that manage an API product.
Ideally, product owners can use developer portals to:
- communicate and get feedback about the product road map,
- gather new ideas for product features,
- ideate new features,
- get feedback about the popularity and performance of current features (e.g. via voting or usage statistics),
- build a relationship with the user community and test new ideas, e.g. via forums that can provide information about users.
4. Marketing
Apigee, our partner, published a white paper about developers hating marketing. Yes, developers prefer to see code instead of marketing copy, but it is also important to keep in mind that your developer portal contributes to your marketing objectives.
Marketeers need a developer portal to:
- perform well on search engines, so that new leads will find your API,
- have a section where decision makers can learn about the benefits and features of your API,
- be an effective conversion tool, that helps to qualify leads,
- measure the effectiveness of the API marketing program.
We believe that it is manipulative marketing that developers really hate. Marketing that tries to directly influence emotions with little substance or evidence about the actual benefits of a product. Like any other human, developers sometimes need help to make decisions. If you have a great product, and if your marketing content is factual, developers might even welcome that marketing and help spread it. But since the content needs to be evidence based, this type of marketing starts to look a lot like well executed documentation, with adaptive content that opens with claims that are backed by layers of increasing detail.
5. Sales
Recent innovations in lead generation tools and marketing automation have blurred the lines between marketing and sales. This trend goes hand in hand with an increasing number of automated processes that are triggered when a potential customer interacts with marketing assets. The developer portal, as the digital gateway to your API, plays an important role in facilitating these new hybrid processes.
A company’s business model influences the types of sales functions you need in your developer portal. Developers act as both implementers and decision makers and will play an intermediary role between your business and your API end consumers: a developer portal, therefore, often will have business development, partner recruitment and sales functions.
6. Developer evangelists
As Christian Heilmann explains in his book on Developer evangelism:
“Developer Evangelism is a new kind of role in IT companies. A developer evangelist is a spokesperson, mediator and translator between a company and both its technical staff and outside developers”.
Developer evangelists (or developer advocates) help a company to bridge the gap between its developer customers (developers of the API client) and its sales, marketing, and product development departments.
This new role is indispensable indeed: developers require more authenticity and responsiveness than the sales and marketing departments traditionally exhibit. Developer evangelists perform a range of jobs to help you grow your API. In a discussion at CLSx London, we identified a number of jobs a developer evangelist performs:
- community manager
- writer
- engineer
- teacher
- speaker
- event manager
The actual roles that an individual developer evangelist will take on depend on the size of your API team (think unicorn magician on a collision course with burn-out). It is probably healthier to split up tasks between several specialists.
One of my key learnings from DevRelCon 2015 was that that developer evangelists typically will report to a product, sales, or marketing department. And that the type of department they report to influences what jobs and what specific tasks they prioritise.
7. Support
Maybe the most important role of a developer portal is self-service support. Without proper documentation, companies will spend an enormous amount of time and money on workshops and trainings.
A portal could opt for various support resources:
- Staffed support options: e.g. a FAQ page, knowledge base page, or support pages (like a contact form or a live chat window),
- Peer-to-peer support: e.g. community sections, forums, and third-party community pages.
The formula for combining several support options depends on your primary personas, your business model and the maturity of your API community.
Investing in a support team is expensive, but the results of their interactions with various user groups are indispensable. The support team:
- provides feedback on the current documentation,
- adds new value to the current documentation in specific problem areas.
In "FAQs, Forums and Other Support Resources" we analyzed the characteristics of support options and looked at how they involve users to develop information about the problem areas in an API’s use.
8. Documentarian
Documentarians, or technical writers, write product specific content, like tutorials, guides, API reference, and onboarding information for an API.
While they might have a technical background, they are often not practicing developers. In other words: they need a portal that allows them to manipulate content without necessarily having to work with the command line or to consult with a developer (we already mentioned the flipside of static developer portals, where changing requirements always comes down to developer work).
Documentarians need a portal setup that:
- allows them to stage content and efficiently test the documentation,
- can publish the documentation format their team has chosen (e.g. Markdown, DITA, Restructured text, Docbook, or Asciidoc),
- integrates with the authoring tools that they use,
- provides them with an accessible publishing tool chain that is easy to operate,
- provides an efficient writing environment that doesn’t require elaborate initiation processes to start writing, so that it becomes easy for people to contribute documentation, even if they are not full time involved in a specific project (e.g. I have heard stories about writing environments that require an elaborate synchronisation process before each writing session),
- provides tools that make it easier to ensure quality.
Developer Portal: Strategy Series, Part 1 Through this series of posts we aim to provide you with strategies for raising the standards of both internal or external developer portals.
