In this episode of the Cherryleaf Podcast, we look at the skills needed for developing a developer portal.
We also talk about our new e-learning course “Creating API documentation and developer portals”, and Google’s recommendations for the content needed on a developer portal.
Transcript
This is the Cherryleaf podcast.
Hello and welcome to the latest episode of The Cherryleaf Podcast.
In this episode, we’re going to be looking at what skills do you need for creating a developer portal?
It’s a question we’ve had to ask ourselves in recent weeks, so we thought it would be a good topic to cover on the podcast.
So there are two ways that we can address the question. One is to look at it from a recruitment perspective, from a company that’s looking to hire somebody.
The other side is from a training perspective or personal improvement side, where you’re looking to improve your skills, or you’ve got people in-house you want to get involved in writing developer portal content and you want to update or improve their skills.
So let’s start with the recruitment side.
Then move into the training aspect.
The two are related and in fact the training one is probably more important.
From a recruitment side there is a shortage of Technical Writers with the right skills or developers with the right skills to create good, high quality developer portals.
Now part of that you could see as being that they don’t have the skills that are required.
The other side is, an it’s often the case, that it indicates that companies have too high expectations for candidates for the job role.
That they put too much into the job role, and they’re ending up in search of what’s called unicorns. They ‘re looking for people with skills, but those people with all of those skills just don’t exist. And it’s a common pitfall, I think, that many software companies fall into.
And sometimes when they’re advertising this role which causes this pitfall, is that they want somebody who is a great developer and a great writer.
And the reality is that the two roles are two different career paths, two different roles and it’s rare that somebody is going to be good in both aspects.
So you’ll see job roles where they’re looking for people with excellent writing skills. Looking for experience of having written API documentation in the past.
And able to programme in JavaScript and Python and C and goodness knows what else.
And those people just rarely, rarely exist.
So there is a need for training, for people to improve their skills.
From both angles.
From developers who are looking to improve their technical writing skills. So if they are tasked with writing the content as well as developing the API,
Or if they want to focus in on writing content.
That’s one audience
And the other audience is technical writers who come from a traditional technical writing background aimed at end users who want to improve their skills and can write content for this more developer more programmer orientated audience.
Because of the growth of APIs this huge growth that there’s been. That there’s opportunities for them to get more work to improve their skills to develop.
For both audiences, in fact, there are a set of core skills that are needed when creating API related documentation and developer portals.
And that is the fundamental aspects of technical writing. The ability to write clearly.
And in a way that reduces ambiguity
To structure the information so it’s clear when you’re talking about one thing and clear when you’re talking about something else.
A clear structure in the sense that there’s a predictability. There’s a scent of information that makes it easy for the user to find the information they’re looking for.
And often it involves writing in a topic-based way. So topics can be reused. Topics can be focused on certain types of information, and they can be written in an optimal way suited to that type of information.
So task-based information is written in a way that makes it easy for people to follow instructions.
So typically that can involve numbered lists
And related to that, and the way which topics are written, writing in a way that it makes it easy for the user to be able to spot when they’ve gone wrong
And have the information there so they know what to do to resolve that mistake to get out of that error.
So that core set of skills is needed for both audiences.
And in fact, we have training courses for those two different audiences.
We have a technical writing foundation course which is aimed primarily at technical writers.
And we have a technical writing for developers course, which has those core skills and is orientated or focused more towards the developer documentation.
But in addition to those core technical writing skills, for API related documentation, for developer portals, there are additional skills that are needed.
Because the audience is different from other types of documentation the audience is developers, it’s a technical audience.
And the relationship between the documentation and the product is different as well.
With many products, software and hardware products, you can sometimes use them without needing to read the guides. You can get by. You can struggle through. You can learn by your mistakes.
With API’s, that’s a lot harder if you don’t know what resources are available. If you don’t know the location of those resources.
If you don’t know how to sign up to get API keys.
Then it’s almost impossible or it is im possible to use the API.
For an API, the documentation, in many ways, is the product.
So if we take the developers and that audience and those core writing skills.
They’ll want to know what does the audience want?
What types of content should they provide on the developer portal.
What’s the best way of explaining complex topics, particularly if they’re unfamiliar with the complex topic and they need to explain it to a programmer who may be less skilled, less experienced, or unfamiliar with this type of concept?
And to be familiar with what’s changing within developer portals, the emerging conventions and standards and styles to make sure that what they create is of a suitable quality compared to competitors in the marketplace.
For technical authors or technical writers as they’re called in the states.
It’s a slightly different requirement.
They may not be familiar with what API’s are.
They may not be familiar with how an API is used.
They probably don’t have much of a programming background, so for that audience.
The skills and experience they need in addition to those core writing skills is
They need to know what an API is. They need to, at a basic level, know how to use an API.
And that can mean using tools that don’t require programming so we don’t necessarily have to have programming skills.
But the ability to get information from an API, they really need that basic experience.
They need to understand what the audience wants. Again, like the developers do.
Again, we need to know the types of content that the audience will want.
And also they will need, like the developers, to know the emerging conventions and standards and styles, other API portals that developers might be using are offering. So that their products are suitable quality.
And again, specifically, I would say for technical writers, they need to know how technical do they have to go.
Do they need to know how to write a code sample? Do they need to know how to write a basic program?
And also both audiences need to know, for this type of technical content, what is the best way for presenting this type of information.
So why have we been asking that question ourselves?
And the answer is that it’s time for us to update our e-learning course on developing API documentation. Because in addition to those technical writing courses that we offer, we’ve also had for number of years, a course specifically aimed at how we create documentation that’s focused on APIs.
And the reasons for changing the course? Well, there are a number of them. One is around the exercises. So when we wrote the exercises for the course we thought we’d write them around APIs to do with hospitals.
Because that was something that everyone understands.
What a hospital is.
We’ve all got some experience of that.
And at the time there was a big growth in an emerging API standard for healthcare called FHIR, the FHIR standard. That meant that lots of APIs from lots of different vendors that all followed the same structure and standard. This was because governments and other bodies were saying healthcare software must come with an API, and it must conform to the FHIR standard. So there were a number of open APIs with the same resources.
Since then what’s happened is, of course we’ve had COVID, so talking about hospitals and people going into hospital.
It’s not really appropriate for these times. I think people have had enough of talking about hospitals and medicine,
And also because the FHIR standard has become accepted and adopted, a lot of the open FHIR demo and test APIs have closed down.
So it’s been a challenge to keep the exercises up to date.
And like lots of situations with API’s, the documentation is also developing and changing and emerging and improving.
There are now more recent standards and conventions that are emerging from different vendors.
Also, in addition to Rest APIs we now have gRPC APIs.
Probably if we go back to when we first originally designed the course, it was the case that lots of companies simply wanted their documentation to look like Stripe’s API documentation. Stripe was the poster boy or poster girl within the API world.
Well, we’ve mentioned in previous broadcasts, I’ve been involved with the DevPortal Awards.
And the winners from that are coming from a much more diverse background.
We’ve got winners from fintech, but we’ve also got winners from the Internet of Things, from software companies, from databases, large companies, small start-ups and so on.
And so there’s many more ideas around as to how to create great content.
And at Cherryleaf, we’ve learnt good practise from writing content for our customers.
Over time the tools have changed. There’s many more tools around and different options.
And also our original course was aimed primarily at technical writers who are unfamiliar with API’s.
So we’ve taken the opportunity to change the course so it is suitable for both technical writers and developers who are involved in writing documentation.
So let me share a little bit about the structure of the course and then some of the content that it covers.
What we’ve decided to cover in the course are the basics that technical writers need to know. What is an API;using an API.
And then content that developers and technical writers both need to know.
And that is the basics of writing API documentation.
Design patterns in API documentation.
The look and feel.
And structure of the site.
The authoring tools that are out there.
Managing an API project.
The main sections are on writing the API documentation. That area is probably the one where we’ve seen the biggest area of change in recent years.
This is what we’ve seen through the developer Portal Awards.
Also, through seeing what training recommendations are being made by Google to their internal teams in terms of the type of content that’s provided.
So what we’ve done with this new course is structure the content section around the type of content that Google recommends its internal teams create for their API’s. Now, in reality, Google doesn’t provide all of these types of content for all of their API’s.
But it’s important, we think, for people to be aware of these different types of content.
And then they can make the decision as to whether they want to include them on a developer portal or not.
And to be aware of the best way of presenting these different types of content.
And to see examples from other companies as to how they have presented this type of content.
So let me share what those recommendations are that Google makes.
And they are conceptual information. Understanding the basic concepts of the API and the information that the API is providing.
A cookbook. That is, a walkthrough from beginning to end of a specific task. For example, getting a response or an application working.
There’s the API reference.
There’s a getting started guide.
there can be tutorials
And there can what’s called colabs, or code labs
There can be what Google calls one pagers. These are summary of what the API or the range of APIs do. The benefits for using them, how to get started, the responses you’ll get from them. How to get an API key. That type of information.
Case studies are those examples from other people that are have used the APIs and the benefits they have got from them.
There can be cheat sheets. Quick reference information for people to find particular resources, ways to get information from the API.
Google recommends an FAQ. We talk about the pros and cons of having FAQs.
And release notes and changelogs.
So what we’ve done around the course is we go through those, showing examples,
If you’re interested in the course, what we’ve done is, we’ve made an early release version of the course, and included it in our intermediate and advanced bundle course.
There is a little bit of development work needed on it.
We need to add a few more exercises, and we’ve got to add a summary .
The rest of the course of done, tested and published.
And if you don’t know about intermediate and advanced course.
It’s a bundle of ten courses. You can take one course, two, three, or all ten.
You pay monthly, and you can cancel at any time.
So it’s similar to Netflix.
If you’d like to take a look at some of the content in the courses, you can see that at cherryleaf.Teachable.com.
It’s probably worthwhile recapping, going back to that main question that we had.
What skills are needed when developing a developer portal?
It’s still good, excellent technical writing skills. Being able to write clearly, a clear structure. It’s having an empathy with the audience, understanding what their motivation is, what they need to know so they can get the job done.
So they can get on with what they want to do.
In addition to that, it’s understanding what APIs are.
And more recently, it’s an understanding of how other companies are presenting different types of content to answer those questions.
Those different types of documents that are being provided by Google and others.
But what do you think? What other skills do you think those who are involved with creating developer tools need?
You can let know via Twitter and my handle is @EllisPratt.
Or on LinkedIn.
Or you can contact us via email info@cherryleaf.com.
And we can revisit this topic in a future podcast episode.
I think that’s it for this episode.
I look forward to the next time.
Leave a Reply