Cherryleaf’s Ginny Critcher and Ellis Pratt discuss using the Redocly platform to create a developer portal and API documentation.
More information:
What is your developer portal’s KPI score?
Transcript
Audio file
Transcript
Speaker 2
This is the Cherryleaf podcast.
Speaker 3
Hi everybody, welcome to the Cherryleaf podcast. I’m Ginny Critcher and I will be talking to Ellis Pratt today. He’s going to talk a little bit about our experience using Redocly on a recent project.
Oh maybe you’d like to start off by giving us the background.
Speaker 1
Yeah, we did a project recently. A documentation project in house for a startup in America and they decided they were going to use Redocly as the platform for creating their developer portal.
And Redocly is a fairly new platform, the developer portal bit of it is still in officially in beta.
It’s getting more attention in recent times. It’s the first time we’ve used it, so I thought it might be useful to talk about our experiences with it. When we came in was that there was a startup.
And they had a product piece of software where it could be used using a Python client and they were going to be developing a Rest API so that clients their customers could use it in that way, so that meant they needed documentation for the rest API.
And they also weren’t happy with the contents that they had already, so they came across us. They did our quiz on What’s your developer portal KPI score? and emailed us to say
We’re not doing very well and can you help? And so we were engaged to reorganise and restructure the content they already had.
Which lots of it was just moving stuff around into a more logical place and making the English a bit clearer and having content relating to this new API and how they could use it. So the stuff about getting started and troubleshooting and and all of that.
They decided to use Redocly as the platform for the developer portal.
So that was going to be a docs section next to their websites and also to help them manage the process of creating the API in the OpenAPI definition file as well.
So that’s sort of the background of why we we used it.
Speaker 3
Yeah, perhaps you could outline for us what is Redoc and what is Redocly?
Speaker 1
So, rather confusingly, if you’re not familiar with it, there’s one product called Redoc and one product called Redocly, and they’re both by the same company, but they do slightly different things.
Redoc is free, it’s open source, it’s it’s on GitHub and it’s been around for a while and you can use that if you’ve got an OpenAPI specification file or what’s known as the Swagger file. The thing that defines what bits of information they’re going to be shared via an API.
You can take it that Swagger file OpenAPI reference file you’ve created, specification file you’ve created
Run it through Redoc and what it will create is documentation API reference documentation so it’ll tell you the different methods and where they’re located and what the parameters are allowed. And so for generating basic API reference documentation. You can use it and it’s a popular tool for that.
And so what they’ve done off the back of the popularity of that is add extra features and functionality to the reference documentation and the other stuff that you want when you’re creating the other documentatio and made a product which you can pay for called Redocly.
And there are bits to Redocly around how API’s are created or the API lifecycle and older bigger companies rather than small ones.
So it’s not going to what those bits are. Does that make sense?
Speaker 3
Yeah, I think so. If you could expand on that that would be great. Can you tell me a little bit about what sort of documentation can you provide if you use Redocly?
Speaker 1
I can do let me start a little bit before that, so there are one of the things that Redocly can do is help a company create this Swagger file with this API OpenAPI definition file. So most the stuff that we’ve dealt with on projects there’s been like one API definition file and we document that with larger companies and with more complex APIs.
Well then have that single file. They have multiple files that put together to make a definition file and what Redocly can do is help that complexity that’s involved with those more complex APIs. What happens in that situation is you have a master file or a main file.
So we don’t use master anymore. We use a main or root file and that sets the locations of where these subsidiary files are and.
So there’s a main structure, and then these ones, and then different people can work on these different areas. And in the case of this client though, we’re using a format for these subsidiary bits called gprc, which can make an API go faster.
Which we didn’t particularly get involved with, but but they do that and what can happen is, is that as you’re building these different bits and making up that specification file, what reductively can do is check that all these different bits when they’re put together all are consistent and coherent and then validated because there’s a danger that one person will use one definition or one location, somebody else to use another, and then when you join them all together it falls over. So Redocly has got some tools for what it calls validating the files and then bundling them together so they make this single file and to validate it, there’s what’s called linting, and that’s checking that the terminology and the links and all of that are consistent.
They are correct, they follow a specific design standard or style so you can have like a single source of truth in order called dependencies or fit together more put towards that.
Redoc also offers an extension if somebody is developing in Visual Studio it can do that. To developing your code in that developer environment, so we didn’t really get involved in that bit.
Apart from going in and looking at some of the descriptions of these different methods.
And making sure they were clear and usual things, switching it from passive voice to active voice so it made it made it a little bit clearer, it does that, and then what? It can also do like the Redoc is automatically generate reference content.
But what you’re giving? In addition, when you’re paying for Redocly over and above the free version is it will add in some extra bits, so we will add in a search.
It will allow you to have a version 1, version 2 and version 3 to switch between the different versions of the reference content.
You can have it without the Redocly labelling and branding. It’ll be faster. You can change the look and feel.
And you can also have code samples that it’ll automatically generate, so when you have a reference point for creating something, it can create a code sample in.
Uhm, let’s pick a language in Python. It can create a code sample in Ruby and that will be there in the reference documentation automatically for you as well.
And it’s faster. The way in which it generates the API reference documentation is quicker and faster than the free version.
Speaker 3
What kind of costs, are we looking at?
Speaker 1
So those are two bits that we did and that was mainly done by the development team. There’s a third bit called in the actual creating of the developer portal itself, which is what we did but to answer your question directly, there’s different versions of a free version for private use. A professional version, which is pretty much what most people go for.
And then there’s a a fully customizable enterprise version where it’s you know, calling for pricing or callers progressing. So the cost for the professional version is 300 a month.
$300 a month, which is $3600 a year.
Which, if you’re a technical author, sounds expensive when people are struggling to try and get people to justify or get the budget to pay for an extra licence of Flare or RoboHelp.
That does sound like an awful lot of money, but what you’re doing is you are using that to do this conversion process for the API.
And that’s generating that content for the people that are actually writing it all through the content. They’re doing that in a text editor.
They’re doing markdown pages, so if you have one author or 10 authors, you don’t need another version of reductively you still have that one version.
So if you think about the cost of Help authoring tools and the fact that they are by user and the more offers you have, the more expensive it gets, then it that pricing starts to make sense.
There’s a third bit to Redocly, so if I go back to that so you can generate reference content, the documents you can use it to build your API specification file. If you’re a developer, what it can also do is that other stuff that you want on a portal.
So if you just have API reference content, it’s not great to use if you don’t understand what it is. If it’s a reference for create an index or create a vector and you don’t explain what an index or a vector are, then you’re going to get stuck very quickly in using the API. So particularly this client they they had stuff, but it didn’t.
There wasn’t. They needed getting started. Information that was a lot clearer. They needed the concepts explained. It didn’t have a troubleshooting page. The process could be made clearer, so there’s a need to to add extra content to it.
So what you do is you write your content in markdown.
And you then push those files up to a GitHub repository and what Redocly does is it converts those markdown files into web pages as a documentation portal.
And what you can do in addition with Redocly to markdown pages is you can also create what are called MDX pages and then markdown pages where you can add some react JavaScript into it to make the page look a bit more jazzy.
Speaker 3
But what did you like about it? What was good about it for you during this project?
It was interesting to use in we really were embedded in with the developers because the developers were writing the APIs in repositories on GitHub. The documentation was being written in repositories and GitHub the process for approving the code was the same as the process for approving the documentation and the developer portal side of things.
This was closely linked with the reference content that was being generated automatically. Now there is a feature that we talked to which we haven’t used or the client hasn’t implemented yet, which will be very interesting. One of those in the Getting started guide and explanations and the overviews were some code samples of how to do things over and above what was in the reference stuff.
If something changed in the way they did the API, then we would have to go in and change the code samples or they’d have to tell us what the changes.
So the code samples were and go in and change that in the getting started guide or the overview because you can break down the API into these little files. 1 the capabilities that you’re meant to do with Redocly is also be able to embed.
Add those fragments of code into the user documentation as well, which means there’s the potential for the developers to change something in the API and automatically the code sample in the getting started guide changes also. So not only does the API reference bits automatically change the code sample there so does in the reference side and that would save a lot of time and effort as it changes.
Sometimes the welcome portals can be a little bit dull because markdown is limited in what you can and can’t do with how it looks and the ability to do these index files just give more scope for that, although the So what you can get with result please. You can use a template.
Which is a developer portal they created with look and feel, and then it’s populated with a tutorial on how to use the application and basically what you do is you delete all the pages that they’ve created for how to use with locally and you replace them with the pages for your portal.
And it was a little bit tricky to make sense of how to understand the react side of things, but if you are more familiar with the JavaScript elements than all of our Web developer background, I’m sure that would would be more beneficial.
So the template itself is relatively easy to customise. To change the photos and the headers.
Pretty easy, just to change the logo of the site. It took him just a few days. We were able to take the template and make it very much the clients look and feel with their fonts, their colours and all of that and that really helped because they could suddenly say yes. This is what it’s going to look like. You can also if you’ve got multiple API reference specification files. These Swagger files you can have a number of those in your portal, so if you’ve got an API catalogue with different API’s, it’s got the ability to manage that complexity as well.
And also the people that are writing the content and working for ridiculous as a number of them that are on the Write The Docs forum the Slack channel I posed a couple of questions on that and they messaged me and said if you’ve got any problems just let me know.
So as an author, there is a sort of a back channel. so now offers if there are any issues where they seem to be very willing to help and guide people to using the platform, and that’s that’s nice to see.
Speaker 3
Yeah, that’s great. No, that’s really helpful.
Speaker 1
Yeah
Speaker 3
Lot of positives. What about any caught any things that you didn’t particularly like? Things that not so great?
Speaker 1
So if you’re used to a background of a help authoring tool, when you create links and you move topics around all of the links go with you and there’s a style sheet and that can be very visual. So if you change the styles of things, you can see what the outcome.
One is when you’re working with markdown, you’re using a text editor and or using a markdown editor, and you can get a sort of WYSIWYG thing where the headings are a bit bigger than the text.
But the link tracking is more you typing in a hyperlink for where you want to go and if that file moves around, you’ve got to remember to update that change in the link and that becomes very time consuming. Particularly start changing file names so they’re all consistent or following conventions so.
And there are these linters and they will go through and they will tell you if there’s broken links, but it’s.
It’s a slightly different model to what you used to. It is a little bit frustrating in that it’s you’re not working in a content management system where it’s doing that in the background.
Yeah, the stylesheet that you get with reductively is what’s called a .TS file, and it’s got lots of styles all commented out, and then you could uncomment the ones that you want.
It’s always in style sheets. If you look at somebody else’s stylesheet, it can be a real nightmare to try and work out what on earth is going on, and this was the case and we did some changes and got it to look OK. And then they were going to get their graphics designs to come in, and the graphics designer looked at the stylesheet and then said this doesn’t make sense to me. And I think in the end one of the developers did some other minor tweaks to the Starship, and in some ways you could, I suppose start from a completely your own stylesheet and go from that.
What you get with ridiculous you can have navigation on the left to all the different pages and you can get on the right in Page navigation to all the headings in there.
And if you don’t include a page in the file that contains all the things that are going to appear in the navigation, it will still appear, but it won’t have the look and feel correct the way that the navigation.
It’s done is it’s done by indenting a certain number of spaces, and then it can have higher revealed parent and child type links like you can get in other help files and the like.
But we had a real struggle to get the OpenAPI specification file and the location of that to work and to get this nesting to work great.
Only getting in number of space indentations. It’s just tricky to do that.
Speaker 3
So one of its quirks that going forward, you need be used to it. And no doubt, yeah, yeah.
Speaker 1
I mean, she’d get used to it, but coming from a traditional traditional.
Really cold.
Speaker 3
Yeah, and you’re coming from a technically altering background using sort of technical authoring tools that seems a little different to what we would be used to.
Speaker 1
Yeah, and things like conditional texts where you might want to mark things up and variables, so again you’ve got the capabilities of what you get with Markdown and GitHub markdown.
There are some capabilities for including files like snippets and conditional text and like, but it gets more and more messy and complex.
Do those types of things.
Oh, the other aspects are that when you’re writing in markdown, you don’t have. As I said, you don’t have WYSIWYG.
So the way they get around that is, you install an application locally and in this case it’s a static site generator called Gatsby, and then when you make a change you go.
You can look at the web page and it’s running a local server, so you go to localhost. I think it’s localhost:3000 and your pages appear there and if you help you with how it looks then you can then take your changes. Use GitHub to make your local changes go up to the GitHub repository and then they’ll they can be approved and go on to the live site.
So you’ve got a bit of setup that you need to do to install Gatsby, and to do that correctly.
So it’s an interesting approach, be interesting to see if other clients.
Let’s go with that.
You get nice looking documentation. You get a search, it’s fast and you have this ability within the same tool to to do the portal stuff and the reference stuff and it can help the developers in building this API definition.
It could grow in popularity and we mix it with others.
Speaker 3
Yeah, thank you for that. Ellis, really interesting to hear your thoughts and your experiences on that particular project.
I think I’d like to give it a go and see how I get on, it’s just understanding some slightly different concepts to whatever more than in the past.
But no, I think it sounds interesting, and I think you’ve given us a a great overview. I’d be really good to hear other peoples experiences as well. Thank you very much for tuning into the Cherryleaf podcast.
Speaker 1
How do they contact us?
Speaker 3
How do they contact us?
Info@cherryleaf.com
Speaker 1
The What’s your developer portal to KPI score quiz that they did, that’s on the Cherryleaf website, and I think it’s on the homepage or on the API documentation page. People like taking it and just seeing how they score.
Speaker 3
Gosh, what do they come up with?
Speaker 1
On that, and then, if they want help, they can contact us so so like themselves up to them really.
Speaker 3
Absolutely everyone loves a quiz. All right? Well, thank you very much. I’m Ginny Critcher, and Ellis Pratt, both of us from Cherryleaf. Thanks for tuning in and look forward to next time.
Leave a Reply