1. Library
  2. Arrow Icon
  3. Building Great API Docs
  • Product
SEP 27, 2018 - 41 MIN

Building Great API Docs


In this Speaker Series presentation, ReadMe founder and CEO Greg Koberger talks about API docs and the importance of having good documentation.

  • Introduction
  • Building Great API Docs
    • Documentation & the API Ecosystem
    • Three Principles for Great Documentation
    • Documentation in Disguise
    • The API Journey
    • Topical Guides
    • Reference Guides
  • Q&A
    • What ReadMe Does
    • Differentiating from Swagger
    • Series-A Recommendation for Support
    • Thoughts about Nontraditional APIs
    • Producing Consistent Documentation
    • Best Practices for Integrating Organization
    • Gitbook and Their Place in the Ecosystem

In this Speaker Series presentation, ReadMe.io founder and CEO Greg Koberger talks about the importance of having good documentation for your business. Hear how to make the most of your API docs, deliver truly useful user support, and how to get other products or services to build top of your product or service.


Today we're going to talk about building great API docs. What are some your favorite APIs? Yell them out. OK, Stripe. Close your eyes and imagine Stripe. OK, you can open them. You probably imagined something that looks a little bit like this.

You didn't imagine-- I'm a mentalist too. You probably imagined something like the Stripe documentation, you probably weren't imagining a URL, you probably weren't imagining JSON blobs.

When you think of Stripe's API it's a great API, but one of the reasons you love it is because it's amazing documentation. They've put a ton of time and effort into their API documentation.

Building Great API Docs

My talk today is called Building Great API Docs, but I'm going to talk about how we should think of it more as just building a great API. Because the two should be incredibly tightly coupled. You can't build a great API without having great API documentation.

This is me, I'm the founder of ReadMe. If you haven't used it directly, you've probably used one of our companies that use us. We power the developer hubs and communities for companies like Lyft and Trello and Boxed and Intercom, and thousands and thousands more.

This is Owlbert, he's our mascot. He's going to help us talk about how to build a great API and great API documentation. I love APIs because they give people superpowers. Whether you're a company or just a random person who wants to build a workflow tool, API documentation or APIs lets you build awesome stuff that you couldn't do before.

The reason why so many companies have been built over the past 5-10 years is because they can stand on the shoulders of awesome APIs, like Stripe and many others. The way that developers look these days is very different than they did 10 years ago.

Ten years ago, a developer was someone with a CS degree who did it full time for a job. Now it's just anyone who wants to build a workflow tool.

Many of you here are probably developers and many of you here probably aren't as well, but pretty much everyone here has a little bit of experience with programming. Whether or not you went to school for CS or not, you still want to build something or make something and APIs really enable that. Today I'll talk about three things.

First, is that your API users are your most important users. Next, the only goal of your API is to be used. And lastly, that your documentation is your API. I'll start with that one.

Documentation & the API Ecosystem

When I say, "Your documentation is your API," I mean it the same way that, "The medium is the message," or stuff like that. I don't literally mean that your documentation is your API. However, much like the Stripe example, it is what you think of when you use an API.

It's the UI, the UX that you use and that you interact with when you're adopting a new API. Traditionally, an API ecosystem looks something like this. There's three major parts that are all in different sections. There's the dashboard, that's where you get your API key. That's where if you're really lucky you'll be able to see logs, things like that. Maybe put your credit card in there. But it's called a dashboard or a dash, or maybe it's just part of the main app. It's the part that you interact with that knows who you are.

Next to the API, that one's obvious. That's what you make a call to and get a response back from. Then there's documentation, and traditionally documentation is just very separate from the other two for some reason. It's very static, you'll see the same thing as you will.

Everyone will see something completely the same when they use documentation, traditionally, because documentation is generated in a very static manner. We think that these three shouldn't be separate but rather should be one common entity. You shouldn't think of documentation as documenting your main product, the API, but rather you should think of it as the main product and think of the three different parts of the API as one.

Three Principles for Great Documentation

That's what we're going to talk about today. Three principles for great documentation. First, show don't tell. I don't know about you guys, but when I go to a new page to use a new API I scroll down to find the code snippets, copy and paste it, if it doesn't work I tweak it a little bit and try it again. Then eventually if I still can't get it to work then maybe I'll read the documentation itself. And that's not a bad thing. That's actually great.

People aren't using your API because they want to use your API, they're using your API because they want to accomplish something.

They want to build something and they want to get past your API as quickly as possible. When you say you like Stripe or Twilio is another big one that people talk about.

When you say that you really like one of these APIs you don't care about the API itself, what you really care about is building something cool. Rather than making people construct code samples in their own language and leave a lot to chance, because English is very ambiguous. If someone is reading a bunch of paragraphs of text and they try to translate that into code, they're going to miss something.

Whether it's because the documentation was unclear or because maybe they misinterpreted something, or maybe when you wrote the documentation there is something that seemed really obvious to you but wouldn't be obvious to someone using your API. There's five, or maybe 10 popular languages out there that will cover most use cases.

You should be writing code snippets for your users. Not only does it save thousands of hours of time, because you write it once and thousands of people can use it or hundreds or dozens, but it also makes it so that you know it's right.

When you write paragraphs of text, there's a lot of ambiguity. You think you're doing a good job but someone has to still translate that into code. You can skip any sort of ambiguity and it just either runs or it doesn't run, if you write code samples.

Next is personalization. We traditionally have all grown up, anyone who programs, learning from a book or from a very static thing. This book's huge because it has to go through every edge case, it has to talk about every skill level, different languages, different weird oddities. We don't have to do that. Because with an API we're incredibly lucky. We know exactly what's going on with your API.

We know exactly how many times you've used it or if you've never used it at all. We can start showing content that's directly relevant to the person who is consuming the documentation, as opposed to just having to do the same thing that we did with books where it had to be good for everyone. We can specifically narrow in on the person who's using the documentation at the time and show them only what they need to see. And third is making it really easy to edit.

This is something that traditionally API documentation is built by a developer. It's generated statically, it's deployed, and that's great at first. It's not a bad thing at all. As time goes on a marketer will come over and be like, "Can you mention this?"

Or a customer will e-mail and have some confusion and you want to change it. If it's not really easy to edit it's really easy for your documentation to fall out of sync with the API, or to just not have all the most relevant information. Some of the best companies take a step further and they open it up so anyone can suggest edits to their API.

Whether they provide the documentation on GitHub or at ReadMe, we have suggested edits feature. The really nice thing about that is that if it's easy to edit for your community, let's say someone spends eight hours trying to track down this bug that's driving the crazy and they finally figure it out. You don't want that knowledge to die with them. You want them to be able to contribute back so the next person doesn't have to spend another eight hours figuring it out or 3 hours or and have that repeat ad nauseum.

If it's really easy to edit that means that anyone from the CEO, marketers, and obviously you want some sort of review process. You don't want people just to put anything out there. But if you allow anyone to make really easy edits it decreases the chance that your API documentation is completely out of date.

Our second point is that the only goal of your API is to be used. This seems incredibly obvious, but I've used a lot of APIs and it doesn't necessarily seem to be true.

Has anyone used the Slack API out here? Okay. Some people, great. Whoever designed the API for Slack, if they were to go through some sort of class and be judged whether or not it's RESTful or not, they would fail miserably.

The Slack API is truly horrible when you're judging it based on the Rest standard or spec. The reason it's horrible is because they do some things like, every single request is a post. They don't care about puts or gets or anything like that. Everything is a post. There's no headers, and there's no anything else. You send in JSON as a post and that's the entire API.

It's horrible from a RESTful perspective, but it makes it really simple for anyone to use the Slack API. And that's important for them. There's huge companies that build on top of Slack, but there's also a ton of people who just want to build a workflow tool. They just want to build something quick. They want to get their customer data into Slack, they want to send something to Slack every time something happens. We have dozens of bots in our Slack because it's so dead simple to use. That's the whole point.

Your API is not supposed to be, "Who cares if it's RESTful, who cares how good it is? As long as people can understand how to use it." One problem with RESTful APIs is that they are written for a computer, to a certain extent. You have a resource and then you do some sort of action on it. Some sort of CRUD action.

CRUD is Create Update Read Delete and those translate to, "Create" is "Post," "Update" is "Puts," "Read" is "Get," and then "Delete" is "Delete." They weren't feeling very creative on that one. That's how computers think.

Whereas humans think in use cases, and Slack's API does a great job of thinking in use cases as opposed to modifying resources like you would talking to a database. And that's why Slack is one of the biggest companies in Silicon Valley today, it's because they've built something that tons of other companies can build on top of it.

It's beautifully designed, it's a nice product, but the real value in Slack is that it's an ecosystem that tons of people have built on top of.

We're going to talk about documentation in disguise right now.

Documentation in Disguise

There's a lot of things, when you think of documentation you think of paragraphs of text. Everyone has a specific vision of documentation. I couldn't think of anything that helps someone learn how to use an API, or debug an API or do a better job of using an API as documentation. Here are some things that don't seem like documentation initially, but for us they are hugely important.

Error messages are a great place. They're a huge missed opportunity that a lot of companies forget to take advantage of. No one reads documentation about error messages before, they just react when they get an error message.

You shouldn't make them Google it, you shouldn't make them figure it out. You shouldn't have that ambiguity.

Obviously you should have a code and a message. One of the coolest tricks you can do that's dead simple that really helps people understand and use your API, is putting some sort of URL to the documentation right in the response.

Don't make them Google it, don't make them search for you, especially if you're a smaller API where Google might not have the SEO might not be as good as something like Slacker, a bigger company. Just link right to the documentation.

Some companies take it a step further. Angular, not really an API, but when there's an error in Angular and you hit an error, the console will log a URL. And the URL will go to the documentation that explains how to fix the problem you just ran into, but they take it a step further and include the variable name that you had.

So if you have a variable name that's messed up or I can't find that variable, the documentation will actually say your variable name. There's no reason that we can't get really fun with documentation and tailor each thing directly to the person. Next is change logs.

APIs are black boxes. You throw content in, you get that content back. You expect when you throw the same data in every single time you're going to get the same response back. But APIs are also living and breathing and they change all the time. Because people can't see what you've done, even if you haven't made a major change you could have unintended side effects.

Having a really good changelog where people can go and read through it and understand what changed about your API will help them debug. If you've changed absolutely nothing that probably means that it's maybe their fault.

But if you changed something huge recently, you should let them know so they know, "OK. Maybe it's my fault, but maybe it's the API that changed." Versioning, people have different strategies for versioning the APIs. Bigger APIs do a better job of versioning than smaller APIs, it's not really worth it to do a great job of versioning early on. Either way, you want to make sure that you communicate to users that the version that they started on the next version was changed. All that. Change logs are great. This is a smaller one, but API status.

If your API is, you ripped some code on top of an API and it's coming along great for a few months and all of a sudden it just stops working, you want to debug it and you want to figure out what went wrong. If you get 500 errors or 503 errors, maybe it's your fault or maybe it's the API's fault. When someone goes to your documentation and your API is down, they should know about it. Make sure it's not off on its own. Make sure you do a very good job of explaining, "It's not just you. Everyone's having a problem." Support forums.

We'll get back to these in a bit, but support forums are phenomenal for just being a Wild West of content that doesn't fit the narrative of your API.

A book like this has to include every single edge case, every single weird oddity. Your documentation doesn't have to do that. You can put it in the support forum. If you're anything like me and you Google an error and you see two things, you see the official documentation and then you see a Stack Overflow post. I click on the Stack Overflow posts a lot of times, because I don't have to figure out and read through paragraphs of text.

Usually there's a direct question that's the same as mine, and I get a direct answer back. Use your support forums like that. If people go to Stack Overflow, that's great, but you might as well keep it all in one place and have a really good search so that anyone using your documentation can find exactly what they're looking for. As far as API controversies go, and there's not a lot of them, SDK is one of the most heated. Some people love SDKs and some people hate them.

Most people are probably indifferent, but I like SDKs. The argument against SDKs is that APIs are language agnostic, why would you mess with that? The argument for SDKs in my mind is that they help anyone who's running into issues smooth over the oddities about your API. Every single API has a little oddity. They might try to be as standard as possible or make as much sense, but there's always that little thing, "You need to URL and code this," or, "You need to pass the API key in." There's a lot of weird things about APIs. A bad SDK just makes it more complicated.

A good SDK can really simplify an API and all those edge cases that you write in paragraphs of text can be smoothed over in an SDK for Python or Rails. Integrations. The point of this section is that your API is meant to be used. Sometimes we're way too gatekeeper-y. That you can only use an API if you know Python or node or how to program. But that's not true. The point of an API is that it extends the functionality of your app, and it shouldn't matter if people have a CS degree or not. Zapier is one of the biggest API companies out there and except for their name which has API in it, they don't mention APIs at all.

That's a big one, I know. Other than that, they don't mention APIs at all on the site. And that's because they realize that people can get a ton of benefits out of APIs without knowing how to program. So you shouldn't be too gatekeeper-y about who gets to use your API and who doesn't.

Anyone who wants to extend your app should be welcome, and integrations are a great way to do that.

There's a company called Clearbit if you guys are familiar with it, it's a way to look up data about businesses and people and stuff like that. When they launched they were an API company. They launched and you would sign up and you'd say, they'd be like, "Are you writing Python or node?" And you would tell them, and then you'd get onboarded.

They've changed because they realized that people didn't really want to write code, they were just writing the same code over and over again. They pushed the SDK stuff and the API stuff down the page. And now when you sign up with Clearbit you are greeted with things like, "Do you use Salesforce? Do you use Customer.io? Do you use Slack?" and they have integrations for all these things. Because the point of an API isn't to make someone program, the point of an API is to accomplish something. If integrations can save people the time it would take them to write code, go for integrations.

Our last point is that your API users are your most important users. They are the hardest to get because it requires someone to buy into it, someone to build on top of you, someone to trust your company. They're the slowest to leave because once you get them they're stuck with you and it's more work to leave.

If you have a problem, they're the quickest to get angry because when your site goes down or does something bad they look bad. But they can be the most valuable partnership that you have as a company. Someone is building on top of you and that's huge.

Look at some of the biggest companies out there, Intercom, Slack, etc. They're so big because the other companies who bought into them and who have built on top of them, who've created this ecosystem where every time someone builds on top of you it adds more value to both companies.

The API Journey

Traditionally APIs are thought of as for devs by devs. You think of it as, "A developer wrote the API, they wrote some documentation, and then another developer is going to consume it. And that's true. However there's a few steps recently that add to the equation. It's not usually developers who are just out there willy nilly picking APIs to use, unless it's a personal project.

But if it's a real company building on top of your API, there's a ton of stakeholders. There's maybe the CEO, there's a product manager, there's a head of IT, there's a DevOps person, there's an engineering manager. Maybe if you charge for your API there's a procurement center or a procurement team.

There's a lot of people who are stakeholders for your API at this point. All too often we forget about them and we just think of APIs as, "A dev built it and a dev is going to consume it. That's it." But if someone is going to build on top of your API and really care about it, we need to market it to everyone when you bring other people into the conversation.

If we agree that your API users are your most important users or at least very important to your business, we're going to talk quickly about how to roll out the red carpet for them. How to give them the best experience that you possibly can. First up is marking pages. This is something that if you built an app, a SaaS app, you would never in a million years just drop people into your app.

You would have a marketing page, you'd explain why you should use the API, you explain the philosophy behind it. How to use the API, things like that because like I said before there's more stakeholders than just the developer. You need to convince people before they use your API, so marketing pages are incredibly important, and people leave them out all the time or gloss over them or don't think they're important.

Next up is onboarding. You've convinced them and they're going to build on top of you. At ReadMe we talk a lot about something called MVC, the "minimum viable call." That's the quickest thing you could have a user do that will confirm to them that they have your API up and running. It means that they've got their credit card in, it means that they've got their API key set up.

It means that they have the SDK installed and it means that they are able to make one request, because the first request is always the hardest. Once you get that you kind of play with the API and change some stuff up, but shortening the feedback loop as quick as possible for the first call is really important.

We said before that it was a black box. You throw something into the API and you get something back. It's really frustrating if you can't debug it, it's frustrating if you send something and you get an error. We want to get people to success as quickly as humanly possible, if you want them to keep using your API because you don't know.

They might leave if they get frustrated. As far as onboarding and exactly what that means, it means giving them a code snippet with your API key in it and just letting them copy and paste it. It's really simple. Don't make them dig around your docs to figure out what endpoint they even want.

We'll get to this in a second, but most reference guides are just an alphabetical list and you don't know. You're overwhelmed. You want to figure out what the smallest thing that someone can do as consequential, give them a code snippet for it and make sure they get up and running as quickly as possible. As far as actual documentation goes, what we think of when we think of documentation.

Topical Guides

I always thought when I started ReadMe I always thought of it as lumped together, just one thing. It was just documentation. There's a talk in the Heavybit Library by a guy named Jacob Kaplan-Moss. He also wrote a blog post about this, a few blog posts, and it's about how to write good documentation. We built ReadMe based on this blog post early on. Things have changed since then, but it does a really good job of explaining the difference between topical guides and different types of documentation.

Jacob Kaplan Moss was the founder of Django, which is like Rails for Python. And they were a good framework, but they had great documentation. I started to read more about it and I understood the difference between topical guides and reference guides, so it's definitely worth watching his talk at some point.

Topical guides versus reference guides. We'll get to reference guides in a second. Reference guides are basically a definition of each year endpoints, all that stuff. What topical guides are, and that's what people should see, it's a use case base thing.

It's like sitting someone down and explaining to them how to do something with your API. You don't just throw parameters at them. You pick 5 to 10 use cases and you do a really good job of walking people through how to use it from start to finish.

If you think about an API, there's a billion use cases. But honestly, 8 to 10 can probably cover most of the first or second use cases that people would have using API. Most APIs aren't that insane. Stripe has something like 200 endpoints, and there's way more that are hidden and disappear and show up based on what product you have installed.

But really, people just want to charge a credit card. That's the number one use case. There's more stuff as time goes on, but topical guides is your chance to do a much more curated job at walking people through how to do specific use cases. Like I said before, make sure there is a code snippet on every single page.

It's not all they care about, but the first thing they look for when they use your documentation is some sort of code snippet and you want to annotate those code snippets with use cases and a bit of a story. Next up is reference guides. Reference guides if you're familiar, when I first showed that Stripe image in the beginning.

It's that 3-column layout that you see and it has all the parameters, it has all the end points. It has every little minute detail you need to know. There is a bit of a paradox with reference guides. Reference guides are both the most important and least important part of your documentation.

Reference Guides

When I say it's the most important, back to that whole black box concept, no one can see the code and no one can dig through the code and figure out why something is working or not working. They really only see what they send in and they see what they get back. Reference guides are that place where they can see what they can send in, they can see the different parameters, etc. So your reference guides need to be really good because if your reference guides are wrong people will send the wrong information and they'll get confused.

However, this is where the paradox comes in. Most users should never go to the reference guides.

It's kind of like if someone wanted to learn English or different language, handing them a dictionary and saying, "Learn English now." It should be used literally as a reference, they're called reference guides. They should only end up there if they're really confused or they're really stuck or they have a weird edge case or something like that.

Your reference guides need to be phenomenal. They need to be correct. They need to be on top of things. They need to be really good. But if people are going to your reference guides too much, that means that your topical guides aren't nearly good enough. Because most users should never have to go past the topical guides.

I said we'd come back to this, last up is support forums. Up until now everything should be a story. It was very clear that it's a flow, it's a story, you're bringing people in and you're showing them things, you're explaining it. You don't expect people to read everything, you expect it to be tailored and have a nice flow and narrative.

Support forums are your Wild West. You can put anything in there. Edge cases, weird oddities, stuff like that. For some reason at ReadMe the number one feature that people disable is the public support forums. I really hope it's because they use something like another public support forum. But I suspect that most of the time it's because you're using Intercom or putting an email address out there or something like that. Support forums for APIs should be public. The reason is that every time one person has an issue, I'm sure there's 5, 10, 15, 20 people who also have that issue.

And a lot of people don't email support, developers are very good at convincing themselves that they can figure it out and if they can't figure it out that's on them. Support forums are a really great way to make sure that all these weird oddities and edge cases bubble up and other people can see it. For our API we get way more people just voting and responding to support forum requests than we do having people actually directly email support about our API. Public support forums are incredibly important.

People forget about them. Some people don't think about them but they're a really great way to just have a ton of content that answers every question imaginable. And lastly, documentation is a one way street unfortunately right now. And this is something at ReadMe that we really want to change. Traditionally documentation is whatever the developer writes, they throw her over the wall and then anyone consuming the API that is all they have. When you go to SaaS operation you've all seen every single site now as an Intercom plugin.

It's very clear how to contact people and talk to them and engage in them, and the CEO will email you. Automated of course, but the CEO will email you and I email everyone all the time. Not really. And when you do a SaaS app the communication is there, you communicate changes all over. There's change logs, you can email someone, you can get support and you can talk to people. Apps are living and breathing and we found that the best SaaS apps are the ones that engage their customers. But for some reason, documentation is this static thing off to the side that people forget about and don't really treat it as a conversation.

If we agree that partnerships are done this way, that your API is the way that you and another company can work together. It's insane to me that we don't do a great job of creating a community and a conversation around documentation, and that's what really excites me about documentation. I don't want to be the best platform for writing paragraphs of text, but rather I want to turn documentation from this static digitalized version of a book and make it more of a conversation. Make it more of a partnership.

Make it more of a back and forth between all the stakeholders, not just two developers or one developer. But rather the sales, marketing, CEO, product, engineering, etc.

To sum it all up, we've talked about how your documentation is metaphorically your API. It's what people think about when they use your API. We think that the only goal of your API is to be used, whether it's an internal microservice with only a few internal users, or it's an external API. Whether you have one or two users, or you have 10,000. It doesn't really matter if your API can't be used, then that's not a very good API.

That seems obvious but surprisingly not that obvious. Lastly, your API users are your most important users. If your API users are your partnerships, they're people who are trusting your company enough to build on top of you, to invest in you, to care about you. You should treat them that way. And that's pretty much it. We think that API documentation is just getting started and we're really excited about how we can start to evolve how API documentation works, but that's pretty much it. Thank you.


What ReadMe Does

ReadMe is a platform for building API documentation. At its most basic layer it's kind of like a Squarespace for API documentation. Thanks for this question, I owe you money or something. Some sort of referral fee. So we do developer.whatever.com for tons of companies. You've probably used us without noticing it, because we look like the brand and we feel like the brand. Because like we said, these APIs are partnerships and we want the API to feel very close to the company's branding and all that.

So we do a lot of stuff around making it really easy. We share reference guides, we show how to use an API, we generate code snippets. We try to build a lot of stuff I talked about. And as time goes on over the next few months and years I want to make it even more personalized. We want to get as much away as possible from just paragraphs of text being the way that we communicate how to use an API and getting even more.

We already generate code snippets in every language, we let you show your API keys to your users, things like that. We want to do exactly what we just talked about and continue to do what we talked about.

Make the support forums even better, make the documentation even more targeted to the individual user, know more about the users.

We do basically API documentation that is cognizant of the user, knows about the API, and does a really good job of tailoring it to the customers.

Differentiating from Swagger

I will answer what Swagger is because a lot of people don't know, and then we can talk about how we fit in with Swagger. Swagger was this spec which describes an API, and it's a JSON or YAML file that really goes into detail about all the parameters and everything else. When we talk about the reference guides, the Swagger file would be the data behind it and then it would be displayed. Swagger is a proprietary name. They spun it off into something called the Open API spec.

So now it's called Open API spec, they're on version 3.something at this point and Swagger now is a trademarked name that is owned by a company called SmartBear and they have some tools around it. So there's two different versions of Swagger. There's the actual spec, and then there's a suite of products called Swagger. We're closer to something called Swagger UI, and Swagger UI is those reference guides that we talked about. It describes the parameters, it visualizes the parameters and visualizes how to use it and stuff like that.

That would be a competitor, yes. But the problem with that is like I said before, reference guides are the worst place for people to end up. You need to have really good reference guides but you also want to make sure you have much more before and after that. Swagger UI is statically generated, it's out there but it doesn't do a great job of explaining why you want to use an endpoint. It doesn't do a great job of explaining things like that because it only has the metadata about an API. How do we work with Swagger and how do we fit together? Open API specs, this file that describes your API, you can upload them to ReadMe.

We have a command line tool, you can paste a URL in, you can copy and paste a Swagger file or an open API file. We don't really compete with the open API spec, but rather you just use the open API spec to generate the reference guides, and then we take that and we can generate code snippets on top of it. We can generate a "try it now" thing where people can type in some code, it'll update the code snippet, run it, that's not right. Tweak it again, run it.

When they get it they can copy and paste it, things like that. So the way that we suggest people use Swagger and ReadMe together is we have a tool called OAS, Open API Spec, so you do "npm install oas-g" for global, and that gives you a command line tool called OAS that you can run on your computer. If anyone is familiar with Java docs, Java docs are a way to document your code right inside the code itself, for a job or something like that in comments.

For us the use case and the workflow we liked the most is that you would write your Swagger file right in your code, and then as part of your build process you would just run that OAS command and it would index all your comments, pull together a Swagger file and create it, and then upload it to ReadMe and keep your docs up to date with the code.

So to answer your question, there is Swagger UI which would be a competitor to us. It lets you generate these reference guides statically. We think that's great, and if you want to use that then that's fine. But there's a lot more to documentation than just the definition of how to use an API. And as far as the Open API specs themselves, we definitely support them. You can just upload your open API spec to us.

Series-A Recommendation for Support

I think Slack is great. Obviously I've said a lot of nice things about Slack, but one problem with Slack as far as this is that information goes to die there. If you have an open community you probably aren't paying $5 bucks a month per person. If you're small that still adds up quickly, which means you only get 10,000 logs and people are asking the same questions. I don't know about you guys but I never feel comfortable just asking a question into the ether on Slack, I feel like I'm annoying people and I feel like it's weird.

There are some communities out there that have done a really great job of it, but I don't tend to like Slack for this because it tends to lock stuff in and you can't Google it. Someone has to actually think to join the Slack group, and it's not indexable or anything like that. Stack Overflow is great. I have no problem with Stack Overflow except that if you're a small company, unless you're having someone actively monitoring it and all that it's a little tough. At ReadMe we have support forums, so if you use the product it would all be integrated together.

If you don't use it, stuff like Google Groups is fine. Stuff like Stack Overflow is fine. I've seen a lot of Discord servers, I've seen a lot of Discourse usage. I don't think it really matters as long as it's public, which Slack isn't. As long as it's public it's fine, as long as Google can pick it up and index it and make it really easy to find, that's probably good enough.

That doesn't really answer your question. Google Groups are nice because they are Googleable, clearly. I really like Google Groups because they bring people into the conversation, it feels more personal than just a support forum for example.

I just think whatever you do, just make it really easy to ask questions and make people feel comfortable asking questions.

Sometimes if it's a Slack group or Google Group they'll feel like they're annoying someone, especially developers. So make it really easy for them to feel like you want them to ask you a question. That's what Intercom has done so amazing in my opinion, it's because I no longer feel like support is a burn on a company.

Intercom does a really good job of making me feel like they want me to email them. Anything you can do to mimic that and make it really easy for developers who tend to be the kind who have the "I can figure it out on my own," mentality, anything that makes them feel comfortable to actually message you is probably good enough. I don't really have a specific example or a specific solution, but anything that's public and really inviting tends to be the best.

Thoughts about Nontraditional APIs

This talk was definitely about RESTful APIs. At ReadMe fewer than half of our customers are RESTful APIs. We have a bunch of stuff like hardware companies, some weird out there stuff. We had a company that was documenting snail movements on and stuff like that. It's all over the map. The one reason I focus on APIs is because unlike a code sample or stuff like that, APIs talk to a server and the nice thing with that is that you can tailor stuff to them. Unfortunately, the less data the docs have the more you have to just write paragraphs of text and explain stuff.

And documentation that gets less good or maybe becomes more important is a good way to put it, but the reason I'm focused on API documentation specifically, and RESTful API documentation is because there's so much we can do with that. That being said, I agree. There's certain languages and for example Python has something called Read the Docs and they used to have something called Sphinx, and I won't get into that.

But they have a specific product made for that community that everyone is on. You could argue that MPM is really good for docs for node packages and all that. So, different subsets of things have a strong developer community where we don't have many MPM packages on us because it'd just be on MPM. We don't have many open source projects beyond GitHub where your users are, stuff like that. I don't really have a great answer. Unfortunately for something like hardware where it doesn't hit a server, it's a lot harder to have documentation that directly affects it, but it's dangerous to think of documentation as just paragraphs of text.

For something like Particle or for just anything out there, the more you can do so people don't have to read the manual-- I don't know if you're like me, but when I buy a new product I don't read through the booklet. Anything you can do during the onboarding flow, getting started, anything to make it easier to use.

That counts as documentation, and one thing I'm sure if you all use a bank in the US they are truly horrible. You Google, "I just want to set up paperless post." You Google it and you get this weird helpdesk, and they're like, "Step 1, sign up for bankofamerica.com, step 2 click the accounts tab and tab into this."

A lot of times documentation is like that, where at some point why doesn't Bank of America have a little toggle right there to turn it off, in the development hub? It's really easy for documentation to be too verbose and spend too much time talking about stuff, when at other parts along the line they could have done a better job of surfacing information. Which is kind of weird, we're a documentation company but I'm a huge advocate of, "You shouldn't need documentation for your UI. Your UI should be good enough."

There's a joke that a UI is a joke, and if you have to explain it, it's not a very good joke.

That's true about a lot of stuff. APIs unfortunately, they're a black box so you can't really see it and you need a certain level of documentation. But my rambling point is that anything you can do to obviously avoid people even having to read your documentation is good, and if you really need documentation then ReadMe is great for technical docs. There's other places out there, GitHub's great for it. But just try to keep people from even having to get to the docs as much as possible.

Producing Consistent Documentation

That's a tough point. That's a real huge reason why, back to my bank point, why there is documentation because the person writing the documentation probably can't go in and edit the code and fix anything. A lot of times unfortunately for technical writers they are constricted to just the documentation, just the paragraphs of text and they're doing the best they possibly can. I don't think that I have a real answer because it's an organizational thing.

My argument would be that the companies that succeed the most don't have that problem, and they figure it out however they happen to figure it out. And if you're at a company where the documentation is API documentation or product documentation, it's such an afterthought that the people creating the documentation have no idea. They're just documenting. They have no say.

A lot of times technical writers are contractors and they're not even part of the company. They get no say, no decision making power. They can't do things like add to the product or anything, and I don't think that can be fixed simply. That's an organizational thing and you should always have documentation. But by the time you get to the point where you're at an organizational structure like that where people don't have any say there's probably way bigger problems in the company to a certain extent.

Not to say that it's over and that the company sucks, but it's something that early on you have to bake into your DNA and make sure that you don't lose as you as you grow. Sorry, I don't have a good answer other than try to find a cool company that values a cohesive experience where everyone in the company has a say and can work together and all that. Obviously as you get bigger, that changes.

Best Practices for Integrating Organization

For something specific like that, I believe that there is a place for technical writers and there is a place for generating stuff, and there's a place for devs to do stuff. The best API documentation does little bit of all three.

They programmatically generate code snippets because as much as I think you should generate code snippets for everything, humans are error prone. There's going to be errors if you're writing a thousand code samples and things like that. There's certain things that a computer should do and a programmer can build a way to generate code snippets.

There's things that the devs should do, because to a certain extent the developer who writes it is always going to know more than the technical writer.

But that's not to say that the developers should be the only person, because the developers also have this mentality as a developer of something that should become common sense to you, "It's obvious that I did it this way," and you forget to document and you forget to talk about it. That's when the rest of the people, bringing them into the conversation is really important. Like technical writers or product people, or marketers or salespeople. Stuff like that.

I think Swagger or OAS is really great whether a developer does it. There are two ways to generate an OAS file, it's either as a API design, so you do it before any code is written and you write the spec out, and it's kind of a contract. Maybe an engineering manager will write it and the engineer will agree to the spec, and the marketing people and the sales team will agree to it before any code is written. Or it's used afterwards to document an API and that's when putting it right in the code works a little bit better.

But as long as you have this file that anyone can edit and access, it makes it very easy. There's the concept, "It's called Open API because there's this concept of API should be open and it should be collaborative." The best companies make it so that it is collaborative, it's not locked down. It's not only the developer gets to decide the parameters and etc. It's like any of the different stakeholders get a say. I don't know if I didn't really answer your question, but I talked a little more specifically about that.

GitBook and Their Place in the Ecosystem

GitBook is completely different than ReadMe. There is some overlap of course, but GitBook is really big on paragraphs of text. I'm not against those, because you need those to a certain extent, but I don't think that's the entire thing. Much like how GitBook is one thing and GitBook does topical guides for the most part. They also let you do reference guides and they've got a bunch of stuff, but it's a way to write pages of text.

You can't do things like get your API keys in there, you don't have marketing pages with GitBook. You don't have support forums, stuff like that. I would say that it's naive to think it's going to solve all the problems. It will solve a lot of them. It's specific, it's good for topical guides, and maybe reference guides a little bit. But there's so much more for a good API site.

I don't think that anyone's really using GitBook. They're using it for lots of things, but no one's really using it as their developer.whatever.com. It might be all you need for the specific use case, but there's so many more things that go into building a really good API documentation. Marketing pages, topical guides, reference guides, support forums. Really good search, code snippet generation. I could go on for hours.

GitBook is really good for a very specific thing, which is basically that GitBook is documents with a structured navigation.

That is documentation to a certain extent. But there's way more than just that that you would need for good documentation, whether it's internal or external.