On the Cherryleaf Podcast, we look at some of the common content challenges organisations face with their developer portals, and ways to fix them. We also look at creating a friction log, and the complexity of banking related APIs.
Transcript:
This is the Cherryleaf podcast.
Hello and welcome to the Cherryleaf Podcast. We’re going to look at in this episode. The topic around fixing developer portals.
And as the market has changed in the terms of the products that software companies offer and the growth of the Internet of Things and the growth of APIs, so that’s led to new challenges and new requirements around supporting the users and providing documentation for them to prevent them from getting stuck. So we get a number of different projects in this field and a range of inquiries, ways on how we can help them. Whether we can help organisations in this field.
So I thought a good place to start is to read out some of the types of inquiries that we get.
And then talk about some of the challenges that are faced with developer portals and APIs.
And then the approaches that we take to tackling them so that you’re aware of we do.
Or you might want to take a similar approach yourself if you’re in that situation.
So let’s talk about some of the inquiries that we get.
One is: we want to review and evaluate all of our support centre content, including the API reference documentation, the integration guides, and the product guides, and we want to help to rewrite the content so that it’s factually correct, clear, concise, relevant, etc.
There’s also an interest in avoiding the problem happening again.
Things like: we want to create a documentation process and methodology from beginning to end. And so we won’t internally create documentation and work out ways to identify how that can be used for public–facing content, so that we can have a centralised knowledge base for support staff and for the end users, and to avoid problems if people leave sometimes.
Also within that request can be: can you advise us on the best authoring platform or content management platform that we can use? Or can you advise on how we can improve the existing tools that we use?
Another type of inquiry is one where they ask for a Technical Author, or assistance in improving the API documentation, because they have an API that’s working and is being used by developers, but they’re now taking it on to the next stage and promoting it into different areas over and above the ones they‘ve been working on for. And particularly to less technical audience. That they’re going from there as well the early adopters.
Some of the issues that might be or to work things out for themselves.
Put into a marketplace where people expect a more polished solution, with all the support that a polished solution offers.
So they’re looking to create a developer portal that describes the product, and has a flow that can help people integrate the API into their tool.
And that those pieces of information can be understood by people who are unfamiliar with the subject matter. All the domain knowledge that’s in place. So if it’s a finance application, for people aren’t necessarily familiar with the way in which finance applications work.
And they often make reference to other sites, competitor sites, saying we want our documentation to look like that.
And probably the biggest area where this comes about is within the finance sector: Banking and insurance and the like, where there have been a number of changes in legislation that have affected what banks offer and also the APIs that they need to offer.
So there is a thing called open banking or PSD2, which is a European Union initiative.
And that’s about making the information that banks have on their customers, making that, with the customers permission, making it available to other people. So let me just give a little bit of information on that, and then we’ll talk about another situation. To connect with your bank, a current account, and use that to pay your bills for different things. And you may have a savings account and you might transfer money across from your current account to your deposit account.
And you may also need to borrow money. You may have an overdraft.
What the idea of PSD2is that other software companies can have access to your information and then be able to offer value added services. So the types of value–added services that they might want to offer is to analyse your flow of money in and out during the month, and then make recommendations if you are overdrawn on how to prevent being overdrawn. Or the best place that you can borrow money to cover that loss. So look at your payments in and out and then say, based on that type of situation, the best solution for you would be to get an overdraft for your bank or to get a long–term loan from ABC Company or XYZ Company, and that would be the cheapest way to cover it. Or the best way would be if you could delay paying this bill until after you’ve received this money in, and that will reduce or get rid of the overdraft that’s done.
Or another thing might be that they analyse all the payments that have gone out, and say, based on your expenditure, you’re paying more than average for your mobile phone bill or your electricity bill or your gas bill, and these are providers that could offer that cheaper. Or they might pay you to for you to provide that information.
And then they can anonymized, aggregated with all of the other customers that are out there, and then sell that information to utility providers, and say the average amount of money that people spend on gas bills or electric bills or telephone bills is this. Market research, market insights information, that they can sell and other people can use.
And ways of telling you when it would be a good time to transfer money from one account to the next to avoid getting overdrawn, or to get the maximum interest on your money. Various things like that.
As a customer, you don’t want a third party necessarily having all of your information. You might want to allow them to see some of your banking information, but not all of your information, so you don’t effectively want to give them your username and password to access everything that’s there.
But just bits of information, and so as a consequence of this, the banks have introduced a number of APIs which third parties can use as long as they ask for and get permission within the system of connecting with the API that they can use for getting bits of information. So these APIs provide a limited view of the information that people have or the banks have on a particular person. So it can be what payments they have going out, an API for that, or their balances or their transactions with different things.
A number of different things.
What the banks have also done is offer extra services and additional APIs so they can take advantage of this.
So what this leads to is for the European banks that they have developed developer portals.
And offering a range of financial services based on APIs and basic APIs that other people can use that organisations can connect to and integrate with.
I don’t see the more people they can get to connect to these things and more services that can be offered. The more benefit is for the bank.
Typically what happens within these developer portals you have information on what the product does, the APIs, troubleshooting information pricing, how to connect and so on.
The type of inquiries we get in this space is: how do we maintain the documentation? So that when there’s a change in the service that’s offered, that there’s also a corresponding change with the documentation. The documentation is kept up to date from a product perspective, and the developer documentation perspective.
How do we manage the differences between the sandbox environments where the developers?
Practise and test and understand the API, and then the live environment.
And how can we make the approval process when somebody’s developed a product in a sandbox environment?
How do we keep the information consistent?
Uses correct terminology when there are different teams building different APIs within the organisation?
How can we explain all the relationships between these different APIs?
What they do and how they interconnect, and how one might rely on another?
So these are the types of challenges that organisations are now facing with their developer portals.
So if you not a developer, if you’re a mainstream technical author, this might seem quite daunting, And if you’re a developer and you’re thinking about this, it might seem quite daunting as well.
But in many ways this is like other content challenges like redesigning a website or planning a help file or an end user document.
Couple of extra things in there over and above, because the documentation is pretty much tied with the application itself.
But there are a number of activities that can be done or by using a sword being done internally.
We’ll go through what they are.
One is improving the developer journey. That is the steps the developer takes, things they sign up for the information they provide to connect and get a response out of the API via Sandbox API or Developer API. So improving developer journeys is one.
Another is to look at the existing content and spot where the content is inaccurate. Where there are gaps, where it’s inconsistent, and fixing those.
3rd is improving that content, and also improving the site structure to create a site structure, a conceptual information model where people can have their answers. They can have an understanding of where information is, where they are on the journey, as it were to getting that response from the API.
So where do you start?
What we recommend is, and this came across also mentioned in the podcast that we did when we reviewed the Developer Portal Awards. So the approach that was taken by Bob Watson and Emmelyn and Wang from Amazon, who are two of the judges from that, and that is to look at the developer journey.
Imagine you’re a developer from the start wanting to get a response from the API. Go through and look at all the steps that need to be taken that are advised from the site. So what needs to happen and create what’s called a friction log. And in your friction log, you can have a column for all of those steps that are going to happen, and then another column where you can document your experience of going through their steps.
Was the step of signing up easy, or was it difficult?
What’s the step of understanding what the product do clear and understandable?
And if there are any issues or problems, in terms of the information not being clear or being missing.
Then you write that down in that column for that particular step, and then the column next to it you can then record down any immediate thoughts on how that problem can be fixed.
So you go down through the journey at each point identifying any issues with navigation, accessibility, comprehension. Classic things that you would look at when reviewing documentation and note down the problems that there are.
So the types of questions are:
Go to the site. Do I need it? Go to the getting started screen, register, get an email to confirm identity, login, setup any two factor authorisation, look at the list of APIs and identify the API you want to use. If you’re developing an app for a developer environment registering that app. And then seeing if you can get a response from that API that you’ve connected to your app.
Look at the reference information. Look at sample codes. Look at the responses are there, and then make a query to that API. Look at responses you get back. See if you understand what that response means in terms of parameters and the like.
And so on.
So with that friction log, what you can also then do is identify if there are challenges or problems in the navigation that the person has been taken through. So then you can start to look at defining a site structure so it’s a logical model for where the information is.
With the flow of the steps, to get the developers signed up is as easy as possible or whether they are expected to jump around different places, when it could be made much simpler or more streamlined.
Then take the content that exists today, and map it to this new structure. And this can also look to developing templates, so that the information about the products is clear about what it does. Editing and extending the existing content.
So you’re creating an information template for overview pages, for the reference pages, and the like.
By doing that, you’re seeing where there’s gaps. Where there’s information with content missing, and then you can start to write to fill in those gaps. So having done that, having created a new site structure for all of the content, identifying the gaps and written up the content to fill in that information, using templates to make it all consistent across all the different APIs and products that there are, you have a site that then is ideally usable for the developer.
Linked with that can be then the issues over which tools are used to create the content.
For it to be published, and then processes by which it can be kept up to date.
So that’s comparatively straight forward and similar to what technical for do with sites, websites with end user documentation today.
There are some differences, though. In some complications I mentioned earlier that.
Let’s say customer of a bank. You wouldn’t necessarily want a software product to have access to all of your financial information, and that it is typically limited to just a narrow area that you give as an end user permission for the product to access.
And also with financial information, you don’t want your information going back and forth in a way that a hacker might access and see your bank account details. Think your transactions who you’re paying and so on. So within the financial sector and within this world of PSD2, and other things as well, there’s some extra steps developers have to take.
I have to put in place to get access to this confidential information. Typically, these are done by having things in place, such as something called Oauth 2.
So in this situation, conceptually the developer has to understand what is going on. What I will do is about what’s needed for things like TLS and X.509 certificates, and other things related to this.
And they also need to know how to do it. They set up stage that’s required and needs to be documented. So in those environments as a technical for what you have to do is write this material in a way that a developer can understand.
You have to write in a way where you don’t necessarily commit the bank to recommending products to do that.
And certain certificates getting the OAuth approved.
And so within those environments this Is more complex. This means as a technical author you need to understand what’s going on.
But you also have the skills. Luckily, to explain to somebody unfamiliar with this, could you make this experience from elsewhere explaining what’s going needs to happen? What to do so that then the developers can do that.
So this is a very interesting area. If you’re a technical author to get involved with, because this is very important to organisations.
When the key features that’s going to make companies successful.
If you are involved in developer portals, and you feel your developer portal is broken. Where do you start?
The best place to start is that developer journey, that friction log. Go through and look at all the steps that need to happen for that developer to get to a response from your API, and log down all of the issues as you go along.
Or get somebody to go through and look at all that they face. And that will help you to identify and prioritise the problems.
And then from there, typically it’s a case of reorganising and restructuring the information, rewriting the information, so it’s clear and easy to understand what to do next.
If you’d like to know more about our services around fixing broken developer portals and technical writing services, you can go to our website to Cherryleaf.com. Or you can contact us info at cherryleaf.com.
Leave a Reply