Developer Portals: when Docs become DX
Breadcrumb
- Home
- PronovixBlog
- Developer Portals: When Docs Become DX
For the past three years we’ve been giving our answers to the following questions: What is a developer portal? Who are its stakeholders? What is developer experience? How do you improve it? What is the MVP for a developer portal?
If you are new to API documentation, that might be a lot to digest…
That is why we created 2 options to get a summary of our research: you could ask us to do a developer portal strategy workshop with your API team (we do these for free for potential customers), or you could join us for a developer portal rundown at a meetup near you, Kristof has done similar presenations in San Francisco, Portland, and London.
If you don’t want to wait until we visit a meetup near you, you can now also read this transcript, with links to in-depth articles for the different topics or watch the video at the end of this post.
Enjoy!
A developer portal is where you publish your API’s documentation. You need a site where you can explain how to integrate with your API and build something on top of that, be that an application or a connection with your own software or another API.
Developer portals play not only a technical role, they also play a somewhat obscure commercial role. We don’t like to say that this is a commercial site, but actually it is also about promotion. You have to explain what you do – preferably not in a hard-core manipulative way. For that, you need more than reference docs. How to get started? What does that API do? A lot more than just the very technical aspects need to be explained.
One of the key purposes of a developer portal is that it should be a self-service hub. It should be a place where you can go as a developer, just get an account, and start developing. Most of the time it’s not what you meet: most of the time you request access and somebody sends you an email to which you have to send an email back; then you have to send another email back – after one or two weeks you get access and you can start developing. What you should try to get to is being able to start programming without any human who has to still check: maybe you have to set up a sandbox with example data. If you are a bank, you probably want a sandbox environment so people cannot mess with real accounts. This is becoming a wide spread practice.
A less well circulated purpose of developer portals is their being a trust signal. They engender trust by showing how much investment went into building that portal. They have to show that the API services documented on that portal will keep on existing and will get reliable support long term.
A well designed and actively maintained developer portal shows that an organization is investing in its APIs. — To learn more, read our previous post in our developer portal strategy series
A developer portal is also a mission control for your API strategy. Your API strategy should be adopted to your business strategy. What are you trying to achieve with your business? Why are you doing APIs? It's a little bit of a hype now to do APIs and everybody is jumping on it but not everybody knows what they are doing. Probably you should be thinking about how your API(s) feature in your overall business strategy and how you can make them stronger together – and that needs to be reflected in your developer portal.
Different stakeholders interact with a developer portal throughout an API’s lifecycle. Read our previous post in our developer portal strategy series where we list 8 stakeholders and explain what they need to do their jobs.
Bad Developer eXperience increases support & training costs. If you don't have a good developer portal, your visitors are going to have such a bad experience that you are going to spend a lot more money and time on support and training.
Arguably, developer portals are/should be an API team’s first devrel investment. Probably you need an API first. However, you could argue even there: if you want a portal for internal APIs, you need a platform where people can submit ideas for resources that could become APIs. Have a workflow that leads them through the process step by step, from idea all the way through to maturity and publication.
API friction destroys API value. One way to look at it is to say what it is not: developer experience is not API friction. When you have a lot of API friction, then you have a very bad developer experience.
We wanted to understand the nature of trust issues and to figure out how we can overcome them in order to create a “frictionless” onboarding experience. Here is what we’ve found so far.
One way that I like to look at Developer eXperience (DX) and API friction is to look at them along the developer's journey. So for the developer who is going to be integrating with your API there are six steps they go through and at each steps there are opportunities to increase or reduce this friction. Preferably, you are reducing API friction.
I have been talking about API friction as a conceptual idea, but it was Bruno Pedro who brought it out as its own thing in his article.
Usage of your API will directly depend on the perceived value of your API and the developer experience. Even if you’ve got a really good but poorly described API, if you don’t have great developer experience (because usually these are connected). So both the perceived value and the DX need to go up for your API usage also increase. Both of these happen to be things you can influence on your developer portal. You can explain what the value of your API is on your portal and you can improve the developer experience with your portal.
Inspect the developer journey, what is possible to make DX better along the road? These six steps give you a mental model to look at your portal and think how you can make it better.
The discovery step is about the perceived value I talked about: ‘What is possible with this API?’’
One of the key things you need for this step is landing pages that are easy to find and that help people to navigate your documentation and your portal. The production value of your landing pages – how beautiful and how well-structured they are – has a big impact on the perceived value. This is one of those areas where you can improve the trust I talked about. You need to think about the different user personas that will land on those pages and to make sure that they are going to find what they need.
Another thing you need here is a very specific type of guides: worked examples. Explain how you are going to do something without explaining everything. Just enough to understand the complexity of the process. Caroline Loveridge from Thermo-Fischer Scientific gave a talk about how they have a complex product that could be used for a multitude of solutions and they started doing worked examples for their APIs. She told how they saw a good uptake on that and they are giving more and more worked examples and those became one of the key pieces in their documentation. Brilliant idea.
Once you have convinced people that ‘Yes, this is a great API and you want to use it’ you need to help them evaluate if your API can do what they need. Production quality as a trust signal is also very important here.
I think that having guides and some clear examples of different scenarios where you could use your API can help with the evaluation process.
Reference docs are a boundary: they tell what (not) to expect. They are not the starting point. With just reference docs, you are dropped in the middle and you don’t really know where you are nor how to get started with things. You need “read to learn to do” materials: tutorials that explain how to get started. With SDKs you can also improve the DX: skip over some of the difficulties with authentication. According to many, the problem with most APIs is the authentication step. Helping people to get over that in their favourite platform, for example Drupal, is nice: if you have a Drupal SDK, then you don’t have to figure out how to integrate to Drupal on your own and you have a bunch of functions you can already use without having to deeply understand how the actual API works. Preferably, your tutorials are also applied to your SDKs, this further simplifies things. People just get the SDK in the language they are familiar with and there’s a tutorial that explains to them how to get started in their favorite language. Then you only have to know how to code in that language. So it is probably a good idea to write the tutorials for the SDKs, not the API.
Guides explore typical scenarios and typical problems people want to address. And yes, of course, you need the API reference docs for troubleshooting.
You want to show your developers that you care about their applications, that you care about the integration that they are doing. If somebody builds and publishes an SDK for your API – because this sometimes happens – you want to show that you care about that. To some extent, also for individual apps you may want to show your appreciation and that they are not just on their own. Successful API integrations should have a place on your portal.
This is the post-care: API version updates and such. API uptime and release notes can save the sanity of your customers.
In our previous post, we look at API friction in the 6 stages of the downstream developer journey and explain how you can address it to improve the DX for downstream developers.
These six phases are about your end users' experience. What about the other developer journey, that of upstream DX?
If you have a large organization with lots of teams doing their own APIs, or a large organization with lots of teams that have to do APIs, they need to go through another journey. We can model it with these 6 steps:
If you are doing internal APIs, you want to focus on this upstream developer journey. If you do this right, then the downstream deliverables will automatically get better.
If you enforce reference docs in a certain format, and they need to adhere to overall standards, and so on, that will help to improve the quality of the deliverables that get published in the downstream journey. It is usually a challenge though, to make all your people go through the standards that you established. Arnaud Lauret has a site on API styleguides. There are tools that can automatically check your docs against a styleguide.
You can have a workflow process where you can move to next step in the workflow by adhering to certain criteria. The key could be gamification. Basically, you would do experience design: create a process where you have quality checks and an experience where it is fun and interesting to go through that process. You can have dashboards for showing how many APIs you have, the quality of those APIs. You can have an overview of the APIs with 5-star ratings depending on what criteria they’ve passed.
Most organizations never consciously address the experience of the developers that create APIs, upstream DX. This is only logical, upstream DX doesn’t always need attention: a team that is dedicated to APIs will overcome friction on its own terms. In large enterprise organizations, however, where API development might be a secondary priority of a team, upstream DX can make the difference between a failed and a successful digital transformation initiative. - Read our previous post on internal experience design.
There is another aspect to documentation portals, that of content types.
They help you navigate your documentation.
A lot of people ask ‘How should I organize my documentation?’ It’s hard because ‘It depends.’ Do you have a clear set of categories? Do you have a clear set of users with different use cases that you can use to segment the APIs that you have? This is not that obvious. Sometimes it is just language-based, like Ruby or php. Sometimes it would be product-based, with different product classes.
I think there’s no one-size-fits-all. The famous polar bear book (Information Architecture, O’Reilly) is a good introduction to organizing your content: how to structure information and what kind of tools are available to figure out how information should be structured. IA is a job on its own but this is a good place to start.
It is important to provide your developer portal with an entrance page where developers can start exploring: the “overview page”. What are the different strategies to structure information? What could be the function of your developer portal? What do you have to keep in mind to build an appealing overview page?
### Task oriented help – Guides and Tutorials.
There is no clear definition of guides and tutorials. I think of tutorials as ‘getting started’: they show you where to do something and take you through the process. Guides are ‘How do I do X?’ and they explain different usage scenarios of your API product to make it more accessible to different people. So a tutorial is more ‘learn how to do’ and a guide is more ‘this is all that you can do’, at least that’s my understanding. And of course, you have worked examples which are slightly different.
Why would you make the difference? If the tech writers are sure of the difference, why expect the user to know it? Because they have very different use cases. The confusion comes from these task-oriented help content types having overlapping characteristics.
A good way to grasp the fundamental difference between guides and tutorials is to learn from Daniele Procida’s categorization into four functions of software docs. He splits the content on a dev portal into four categories:
Daniele argues that you need all four. If you have only tutorials but not the how-to guides, then the decision-maker who doesn’t want to do the integration but who still needs to find out if they can use your API, will get lost. If you have only guides but you don’t have tutorials then the developer who needs to start implementing this is going to think ‘This is all marketing’ and they can’t do anything with it.
It’s not good to make the user make a choice without giving a clear definition. On the overview page of the Django CMS documentation, they do a very good job of this: the lines under the titles are not actual examples but an explanation.
In our previous post – part 3 in the Dev Portal Components series – we explore how the sites we reviewed included guides and tutorials in their information architecture, we look at what they covered, and finish with listing what could help to maximize their effectiveness.
I think there’s a continuum between these things, where you can maybe start with a worked example, almost as marketing content that explains in a very high level ‘This is how you do it.’ This then links to tutorials, which explain exactly how to do it. Then maybe guides with specific questions connected to the example. You could make this beautiful connected graph of content.
For internal APIs, you will not get the budget of course.
Software Developer Kits. They are kind of a standard implementation of an API, that you can just drop in your app and it is just supposed to work. Input your key and you’re going. They help to encourage best practices and they simplify authentication for example.
There are interesting things about SDKs. How do you write all these SDKs? How do you keep them in sync with your API? Because your API keeps changing, so then your SDK has to keep changing. If you have six SDKs for six languages, then you have six pieces of software you have to keep in sync with your API, this is a massive headache.
Tristan Sokol gave a talk at DevXcon ‘17 about how you should automate SDK generation. At Square, they have a template that gives fairly structured output. But if you automatically generate SDKs it won’t have all the best practices from the different platforms. You still need people to really think about it, who know what to connect it with and what the popular libraries to interact with are, etc.
There are other ways to do it. For example at Keen IO they have 7 languages that they officially support with SDKs and on the official portal there are also the community SDKs listed, the ones that the community contributed to the project. This is Keen IO celebrating those integrations, putting them also on the site and building relationships with the developers.
The story goes that because there was no SDK in a certain language for PayPal, people started making those SDKs – and now if you search on GitHub, the biggest SDK for PayPal payment API is for an old API version. This can cause all kinds of headaches and you need to think about this. Ideally, if you have people in the community building SDKs for you, build a relationship with them. Give them T-shirts at least, you can maybe give them money just for maintenance. Make sure you can take over their project if they disappear.
You can do an auto-generated SDK and then have a best practices layer on top of it. So you have a mixture of community-designed, hand-crafted and auto-generated.
It is a good idea to write your tutorials for the SDKs, not the API.
Large companies can inner-source their SDKs. Innersourcing is a term coming from the open source world. Take all the best practices from the open source world: code repositories, pull requests, meritocracy and so on – and use it inside your organization. In a large corporation with many departments, they would be doing ‘open source’, but only within the organization. They have access to the code and can see what others have been doing and then contribute to somebody else’s project. Make an SDK, contribute to an open source repository and add it to your developer portal. The next time somebody needs an SDK, they can use yours and build further on it.
What strategic choices do you need to make when deciding on what SDKs to make? In our previous post – part 6 in the Dev Portal Components series – we discuss what kind of SDKs the Portals in our sample group used. We analyze their choices and evaluate them against the principles that Taylor Barnett from Keen IO shared at APIstrat '16.
No developer portal should be without the API references, they are the core of the minimal viable product.
Open API is now the leading specification for RESTful APIs.
A reference for a documentation for an API, defines everything the API can do – what are the endpoints, what are the parameters. It forms a seed for samples generating basic code. It is like the plan that defines your API. Ideally, you start with your specification that explains how your API is going to work and you can use that as a sort of contract between the developers creating the API and the people who will use the API. You can also use the specification to test your API. There are tools that take your API’s specification and automatically test it against your API to see if it fulfills all the promises that you’ve made. It is slowly becoming a best practice to do APIs this way.
Honza Javorek gave a presentation at our February WTD meetup on Readme Driven Development and DREDD, check it out to get a good overview and understanding of the basic principles.
Keep in mind, Open API Specification is not everything, there are other formats, for instance, GraphQL.
One of the pain-points with the spec is how to integrate it with other documentation. If your domain language has certain words you are using in your API that you explain in your conceptual documentation, how do you bring it into your specification and how do you link back to it? Professor Michael Meng and his team are doing research on the best solutions for this combination, for less and for more experienced users. They found some interesting things in their research: developers might think they don’t need your conceptual documentation and they just start working and then they bump into a wall. They saw that people who didn’t have much experience with a certain domain really needed the conceptual documentation and it was better if it was somewhere inside the reference docs. Their research team is looking at how much you can gain in developer experience by including the conceptual documentation into the references.
In part 4 of our Developer Portal Components series, we show how the developer portals in our research sample implemented their reference pages, compare their formats and labels, and try to deduct best practices you could apply on your developer portal.
### Role Based Access Control If you want role based access control, you will need a Content Management System (CMS): tools like Drupal, Django, Wordpress. Sometimes you have APIs that you want to be accessible by some people but not by others. For example, you might have a partner API that you want accessible to certain partners only and you don't want anybody else to know about it. While most of the developer portals are nowadays built with static site generators, Role Based Access Control is still easier with a CMS.
If you are going to have partner APIs, you need to think about role-based access control.
If you are going to have Frequently Asked Questions –which is a big if, oftentimes you don’t want that– but if you do, then don’t just make a long list. Nobody reads that. Make it easier to digest: make categories, give a good search function, limit the number of topics. You could think about graphics if you like that.
Be very careful with community pages on your site, most community pages become tumbleweed towns where nobody ever comes. If you go for it, you will need a community manager who is making the community live. That’s a lot of work. Seeding the forum with content, making sure questions get answered, encourage people who are contributing. If you just put a forum on your developer portal, there’s very little chance it will just work. Sometimes it’s better to go where the developers are already going. StackOverflow is probably the best place to go if it’s an open API because people will be asking questions there anyway. Of course, if it’s a partner API only accessible to certain groups than that doesn’t work. One downside of going to 3rd party community platforms is that you don’t own the conversation. You have to be pragmatic.
A partner of ours, who creates pdf libraries for Java, went on Stackoverflow looking for people who were stuck with questions about how to make pdf work and he would answer them with his library which is an open source library and then he would link back to the code examples on his site. So the answers were on Stackoverflow, but he was still linking back and copying the content to his own platform. He also later republished it as a book. That is cool.
Your paying customers will expect a support team. There are really interesting new technologies, Intercom for instance. I love the combination of support documentation and chat, their automatic reply function.
Be conscious of your support strategy and choose the appropriate channels. Don’t just say, ‘Oh yeah, we’ll put a forum and people will answer their own questions.’ That seldom happens and if it does, it might take weeks to get one answer or you have to have a very active community – keep in mind that everybody has an opinion, but not necessarily the solution.
We analyze the characteristics of a number of support resources and look at how they involve users to develop information about the problem areas in an API’s use. We list pros and cons for the different resources, look at their place in the site architecture, and finally propose best practices. – Read part 5 in our Developer Portal Components series
So where do you start, what is an MVP for an API documentation portal? One way to answer that is to see what questions your developer portal needs to answer.
What information is absolutely essential on a developer portal? What kind of API documentation do you need? Is there a best practice that can be followed when launching a developer portal? We formulated 11 questions and built 3 mock sitemaps that demonstrate how portals can address the different stages of the developer journey.
If you have somebody who can write regularly for your portal then you probably want a blog. Because a blog is an unstructured space where you can prototype new types of content. For instance, if you don’t have any tutorials yet, you can use your blog to publish your first tutorials. If you don’t have any release notes yet, you can use your blog for them. It’s a really nice space. It is also a trust signal that shows, ‘Yes, we’re alive, we’re working on it.’ ‘Just yesterday somebody put a blog post, it must be that they’re still interested.’
Without these four, you shouldn’t launch. You can then add the others step by step.
This was an edited transcript (by Laura Vass) of the presentation Kristof Van Tomme gave at the March meetup of the Amsterdam Write The Docs community. We especially thank Wouter Veeken and Booking.com for being the most attentive hosts for the event and our fellow documentarians for the intriguing discussions.
The presentation was also recorded:
I created a developer portal strategy workshop, that I do to introduce the key concepts of dev portals to new customers.
In previous projects we’ve learnt that the publicly visible portals for open API programs are only part of the picture. Many portals start as internal tools to accelerate API programs and to improve design consistency and governance. In the workshop I give an overview of the different objectives, stakeholders and architectures that can influence your portal design, so your portal will be able to accommodate both your publicly facing, internal, and partner API programs. I’m sure your team has already experience with a lot of the topics that I cover (most of the time I’m coming in when an API team just started building dev portals), but if you think there is value in it for you, I would love to come and do my workshop for you.
Throughout the workshop I ask questions about your APIs, your organization and the objectives of your API initiative. With the answers I compile a report that gives an overview of your organizational and strategic background that we use as a starting point for the architecture workshops my colleagues hold.
Kristof Van Tomme is an open source strategist and architect. He is the CEO and co-founder of Pronovix. He’s got a degree in bioengineering and is a regular speaker at conferences in the API, developer relations, and technical writing communities. He is the host of the Developer Success & the Business of APIs and the API Resilience podcasts.
Articles on devportals, DX and API docs, event recaps, webinars, and more. Sign up to be up to date with the latest trends and best practices.