GitLab GitLab Tech Talks, 4 May 2020

Previous Meeting

⏯

youtube image

►

From YouTube: Minimum Viable Documentation for RESTful APIs | Mike Jang | API The Docs Virtual 2020

Description

Minimum Viable Documentation for RESTful APIs by Mike Jang, API The Docs Virtual 2020, 22 April.

Talk Description:
"To paraphrase a James Bond movie, “Swagger is not enough”. You’ve done the work to set up REST calls for your APIs (Inaccurately known as Swagger). You have reference information. But you discover that few users are actually trying REST calls on your system. You’re wondering: “What else do I need?”

This presentation will describe the Minimal Viable Documentation (MVD) for RESTful APIs, also known as “What do I need for my developer portal?”

Based loosely on Kristof Van Tomme’s presentations on Developer Experience, Mike will describe the MVD for a developer portal, which will help your developers try out your APIs. He will discuss the characteristics of:
- Landing Pages that describe the API
- Tutorials that help the user get started
- Details, or reference information satisfied by the OpenAPI specification
- Work in Progress such as blogs and release notes that show active development

While Mike gave an earlier version of this talk at the API Strategy Conference in 2018, he’ll update this talk for the latest API portals."

API The Docs Virtual 2020 recaps: https://pronovix.com/event/api-docs-virtual-2020

---

API the Docs is an event for tech writers, API developers, product owners and developer evangelists who embrace documentation as a crucial aspect of a great developer experience. The conference is a great opportunity to share and discuss the latest best practices, strategies and new trends relevant to API documentation and developer portals.

Pronovix Developer Portals Newsletter: http://bit.ly/devportals

A

Hi I'm, Mike, Chang and I'll be talking about minimum viable documentation for restful api.

A

Before we begin, let's start with a look at the world in this difficult time, in the hope that we can stay together and yet stay socially distant.

A

At the end of this talk, some of you may say yes, I'm said: we've got great documentation for our api's, for the rest, I have elements of an action plan for you, of course, you'll have to fill in the blanks to match your own api's.

A

If you want to copy my slides they're available online at this URL, and if you forget to copy this I'll, have this URL periodically at the bottom of settled by slides.

A

Now, to introduce myself I call myself a documentarian, also known as a technical writer I work for a company called gitlab and we refer to ourselves as a single application for the entire DevOps lifecycle, I'm responsible for gitlab documentation in our managed space. But that's a long story before becoming a tech. Writer, I wrote a few books, including one on the Red Hat certified engineer. Exam I also helped with meetups for the write, the docs organization. We have nearly 50 meetups worldwide, but for now we're all virtual.

A

At this point, if I were speaking to a live audience, I'd ask you to stand up when I called out your job function, but this is a virtual talk. So let me just say that I'm always surprised that the dubber developers who attend the talk and I'm pleased with the interest.

A

So what is this Minimum Viable documentation, MBD for short, well, James Higginbottom has a template for something similar. He calls it a Minimum, Viable portal and I. Think it's a great starting point.

A

But to me it's just that, as MVD is more than just a bunch of end points it's more than just reading code, you're, RESTful, API Doc's, even your graph, QL Doc's, really your Docs as a whole need to provide a excellent developer experience.

A

So the spoiler here is that what we're talking about is all about the developer, experience DX for short and kristoff ground domain, the guy behind API the docks presented to slide a few years back scribes how developer experience is an inverse function of API friction and the friction you put in your a thighs includes any problems that you might have in your documentation and you want documentation that provides next from developer experience, because developers and the rest of us are people too. You've got your respect. Their time.

A

You a lot of people will ask especially coders they'll ask: why do you even bother with documentation in this age of literal code? All you have to do is just read the code at the meeting of. What's being done, is a parent, so they'll say that code. It's self documented, well I'm, going to make an analogy here. Here's my example of self-documenting code, it's human DNA to be itself documenting in the same way and in fact, in some ways it's simpler.

A

It only has four nucleotides and I won't try to pronounce these, but you can combine them in such complex ways to create Oh plainly to create us and the complexities of those nucleotides takes so much time to document they try to set things up in something called the Human Genome Project.

A

Well, I can't pretend that RESTful API is are as complex as human genes. I can make an analogy here, as there are four nucleotides there are four dress commands, create, read, update and delete, and in a similar fashion we set these up as end points using the specification known as the open API initiative, and there are a lot of people out there. Who've used the open, API spec to create what seems like a world of endpoints, and this is great as a starting point. Thank you open API initiative.

A

It feels like we're covering the world with endpoints, but there might be a problem with this.

A

When you look at it closely, you think. Oh, my god, there are walls, a text I'm fortunate to speak to audiences with a lot of rings. I bet a lot of you know more than one language when I first learned, French one thing I picked up was a dictionary seriously. If my teacher told me Mike, all you need to do to learn, the language is learn. The dictionary I would have walked out in the same fashion.

A

If all you do with your readers is present, end points being a little blunt I think they should walk out. What you need is to present practical experience to give them practical situations, use cases if you will nevertheless the end points and the dictionary their fundamental. They provide a foundation for turning, but what you need to add to the foundation?

A

How do we get to this concept? Called minimal, Viable documentation.

A

Well, there are a lot of good examples out there and the people behind API, the docs have also created a website and a set of awards called death portal awards. Org in preparation for this talk, I'd looked at some of the examples presented there, but before we do that, since we're talking about restful api s, let's back up a second, as some of you may know, restful api s-- came from a dissertation by Roy, fielding and seriously when he created the dissertation and created the term restful.

A

He must have had marketing in mind because when something is restful, it makes at least makes me think of an easy button and whenever there's an easy button encoding, this is the image I get and how it makes me feel. But how do you get to this in reality? How do you get to a good developer experience the secret here to get to a good developer. Experience is to have at least a functional user experience.

A

And for that unique documentation, is this the kind of documentation you want? Well, you look at this wallet text and I'm going to rely on the onion, which is a US humor magazine wherever it's the response, but seriously you want text that actually provides a good experience, because today we write for people who don't read you think about that, and it doesn't make a lot of sense until you understand the background behind that, the spoiler people don't read documentation, they scan Doc's.

A

So how do you help your readers scan your content?

A

It's time to step back in cover a couple of tenants of technical writing when you create a page of documentation, you want to focus key information in your first two paragraphs and for the remainder of that page for subsequent paragraphs. The first three to five words of every paragraph are critical. That'll tell the reader, oh yeah, I'm interested in that too.

A

So how do walk in the shoes for your readers, typically developers.

A

Well, in a previous talk, Christophe presented eleven tenets of ideal world documentation when I first saw this slide, I thought yeah that all makes sense, but then I looked at the slide as a whole and I thought. Oh, my god am I going to have to do all that I mean seriously.

A

We all have busy jobs. I read at least if we're fortunate and we have deadlines.

A

So the question here back you up is why would anyone use my API? That's the answer. You want it to answer in your documentation and if you do it properly, you do it with minimal Viable documentation. Keep it simple. If you do that, and it presented properly, your readers will be able to say. Oh my gosh. This works for me at a glance.

A

So how do we keep it simple?

A

Do we have to cover all 11 points in christop slide? Well, Christophe followed up, fortunately, with a simpler slide. What are the minimum requirements? So, let's take a quick look at this slide. You scan it and you see at the bottom. How can I reach you support, contact details? That's straightforward! You can click, an email address, a support form, even a foot telephone number on your webpage and say check. That's done so we do that and I'll cover the four other details and call that minimal Viable documentation.

A

Landing page now that the world is in the middle of a quarantine, I guess I can say many of us used to fly to conferences like this. Oh, how things have changed, but you can still imagine you're flying someplace with your breast fillet. Api you've landed a hub airport and he be to be routed to some end point you're, hoping for clear instructions how to get there. A good experience at your hub airport.

A

In a few cases, you may need to go through another hub and that's okay, but how do you get to that good experience here? I cite some examples.

A

One example that stood the test of time and in previous talks is Twitter. This is their landing page for the air api's. They have use cases on top simply stated one or two-word use cases, and they have end points you can scan on that same page. To me, that's my boy.

A

A lot of people cite stripe as an exemplar of excellent API Docs and in many ways they are. They have their use cases in the middle. They have their products on the left-hand pane all, but one or one word and they're descriptive. They tell you hey. This is what's going on. You click on that. You get examples that you can follow for quote-unquote, easy wins.

A

So what are the takeaways from this for landing pages number one? You want a functional user experience and since I can't go into depth on how to get to a good user experience, that's really a different talk, I'm going to cite a principle based on this book, which I like don't make me think seriously. If your user experience is making the user think then you're doing it wrong.

A

So what's the action plan out of this number one, you want to set up what you can do and what your customers might want to do in this cases. Number two: you want to layout your API functionality and coordinate it with your use cases and when you do that, you want to follow the principles of of creating a good user experience.

A

Next, our tutorials the reality in the web space. We want to create tutorials that serve the whole audience all at once. If we can deliver our trendek once and it serves everybody, we think yeah. This is great, but what a customer wants his hands on instruction, something customized for their particular needs. So how do you compromise? How do you get between the two?

A

The way I like to do it is with samples you provide a variety of use cases for people you've, let them customize and you've. Let them check you check out for use cases in playgrounds that you provide.

A

For me, use cases are like going to a buffet.

A

You help people see okay, this is the selection we have available and some people may want barbecue and some people might want tofu with hollandaise sauce. Let the Kush work it. What they want.

A

So what are some examples of how people present use cases.

A

The orange dub recite a couple of years ago they had straightforward depictions of use cases based on single words quote unquote. They improve this site with more detail, I personally degree. What partly I personally disagree with this movement towards orgeat health, but everybody is entitled to their opinion on this another example: the neck developer site. They have use cases that same scattershot, but the principle is, let's serve people up above a and let people pick and choose what they need and that's great and once people pick and choose, they can customize.

A

They could salt to taste salting to taste by providing their own URL zero. The access tokens.

A

They have once they do that they have use cases that meet their needs. So how do you do that?

A

You may want to provide own test playground, but there are also excellent third-party test playgrounds available.

A

And the convene associated with test playgrounds is that they enable customization they allow you to set a, for example, set a variable for a customer URL at what that variable flow through your API and then your customer will be happy and say: hey. This API actually works for me when you have a test playground, you're, also integrating your foundation, your dictionary, your API endpoints, at what, when you do that, you're enhancing your developer experience.

A

So what are the takeaways from this? What do you want? Tutorials that reflect what happens in the real world? You want to be able to let your customers customize. What do you provide and you want to provide test playgrounds, so customers can see for themselves? Okay, this works for me. So how do you get there? You provide use cases as a story.

A

You let people insert their URLs in whatever samples you provide and I've covered discussions of custom playgrounds.

A

So through for details, some of you may recognize these end points from the old open, API, 2.0, swagger pet store, and this is great as it allowed people to look under the hood of an API. If you appreciate cars, you appreciate the cleanliness of this interface. It allows you to look under the hood and see all the moving parts and see how they work. So, how do you provide a user experience? That's equivalent?

A

How do you make it easier for your users? This look under the hood of your API I'll cover these five points in the following slides. First, you want to respect newer users or busier users. I mean seriously. We may be experts in restful api x', but our users may not be happy. You may have an admin hook's who works all day with soap and ben's realizes. Oh, my gosh. I've got to make this api work as well.

A

The earth's api hub does a great great job with this in their reference documentation by starting with the basics, reminding people hey. This is what restful api czar all about.

A

My former employer or druk they organize their endpoints I mean they have hundreds of them, but if you have to scan through them all, that's not the easiest thing to do. If you organize them, you help people find the endpoints they need and strike within their API. Documentation provides curl commands, which you can copy and paste into your CLI and see how they work for you.

A

We have another example of a demo environment. This is from Aiden, I, hope, I'm pronouncing that right, I have here a payments, endpoint I click on the playground and I see. Oh, this is JSON format, input on how to set up an order.

A

I click run and I see ah it's a 200 I've successfully charged a specific credit card for an order gosh. This works for me and since I work for kid lab and we're moving to graph QL I feel like I need to Ella straight what we do as well.

A

We have a graph QL Explorer, for which I've set up a specific issue that describes the work that we do. I.

A

Click Play and find information about the issue. If I want more about the issue I can add, or in the JSON based request, no don't JSON pardon me yeah, no I click play and I get get a good result as well, giving me more information and if I want more details, I can click on Docs, and this gives me more information about each of the properties therein and once I get something working. I feel like I've gone to the casino and get a minor jackpot, and this is the feeling you want your readers to get.

A

Other words, if you give people a good user experience, you bring them to a good developer experience. So what are the takeaways from the section?

A

Well, if you get a world of end points based on swagger, which is now the open API initiative, it's not enough, you need more.

A

So what's the action plan here repeating the five steps showed earlier, you explained the basics of: what's a RESTful API, you organize your endpoints, you provide CRO commands for each of your endpoints. Ideally you want demo environments, so people can see for themselves that your API can actually work for them and you do it in a way that enhances the developer experience now, step four or four shirring. Your works in progress, sharing, hope and keeping with the spirit of being minimal.

A

I've split this up into three sections number one release notes: what do you need and release notes at minimum? You need two things describe. What's you described? What's changed with that information? People can look at your release, notes and say ah for this release. This is what's what's now, I can do, and this is what I have to watch out for.

A

Blogposts, this is your opportunity to go beyond your documentation to kalokhe we'll talk about what your product can do in a relatable and conversational way using language that goes beyond what you see in typical documentation to say: hey. These are the use cases. These are the experiences that we have with such cases.

A

Finally, roadmaps these provide your plans for the future.

A

Having people understand roadmaps that they're, not necessarily a commitment that you're going to do something, but there they are a commitment that you're going to try to do something and that provides your customers hope number one, hey they're listening to me number two: this is something I have to look forward to. So what are the takeaways here.

A

You want three things or your works in progress if you want viable release notes. Ideally, you'll also want to share blogs with the committee and also share roadmaps, to say, hey, there's hope for the future.

A

With that in hand, we finished the journey towards minimal, viable documentation, and, yes, the sign says a marathon. But if you look carefully, the timing is that of a half marathon, because seriously this is minimal and once again, here's a link to my slides and with that, since I have a minute to share I'm going to share a bit from my dog Katie she's a Labrador and she gets the ball, and that gives me an opportunity and context to thank my employer gitlab for giving me the time and space to prepare this presentation.

A

For you thanks very much.

A