API Documentation

for Developers

A hands-on guide to creating and maintaining API documentation that kicks ass.

Ever had to work with an API that was poorly documented?

It's like you're in a strange city, and you're trying to find your way. But somehow, your Maps or Travel app isn't working. So you have to ask people you see around. Unfortunately, most other people are lost tourists like you, looking for directions.

As a developer, you've probably had to call an external API sometime, or write one of your own. Either way, you've had to deal with API documentation. Documentation is an integral part of building sustainable software. What's the point of the beautiful city if you can't figure out where to go? What's the point of building a powerful API if your users can't figure out how to use it? Docs are key.

Yet they're often shitty.


Well, writing good documentation takes work.๐Ÿ˜“

It takes time. It takes effort. It takes skill. It takes actually caring.

And beyond the writing, there's lots to consider. What tool do I use? How do I make sure the docs are always up to date? How do I catch inaccuracies? Where do I publish? How do I know if my docs are actually helpful?

But it's worth it.

It saves your users pain. It saves your teammates pain. It saves you pain. Plus it's nice to get compliments on your powerful API and awesome documentation. ๐Ÿ˜Ž

There are tons of resources on the Internet for learning how to build APIs. But there's very little showing you how to properly document those APIs. I'd like to change that.

Writing for devs, by devs.

I'm a developer like you. I've worked with several APIs and built a few myself. After getting bitten by APIs with poor documentation enough times, I got fed up and decided to make this course.

In this course, I'll show you how to build friendly, concise, testable and maintainable docs for your API. We'll explore the hows and whys, look at examples of good and bad documentation in the wild, and do some documenting ourselves. It's gonna be fun, I promise.

It's time to write documentation

that doesn't suck.๐Ÿš€

Let's do this!๐Ÿ‘Š

What you'll learn:

  • What makes great docs great
  • Writing and publishing reference and conceptual materials
  • Publishing, testing and updating your docs
  • Integrating docs in your dev workflow, and vice versa
  • Documentation of new vs existing APIs

What you'll get:

  • Step-by-step videos with text summaries
  • Comparison of real-world API docs
  • Hands-on documentation of two APIs using different approaches
  • Full source code of all examples
  • Dozens of tips + external resources on improving your technical writing skills

Ready to start crafting docs that make your users and teammates happy? ๐Ÿ”ฅ

Enter your email to get notified when the course launches. You'll also get a free course preview.

(Oh, and if you know the developers of those APIs with poor docs, send them the link to this course, will ya? They'll thank you.๐Ÿ˜œ)

Card image

About me

Hi! I'm Shalvah. I'm the maintainer of Scribe, an open-source tool for documenting APIs right from your Laravel (PHP) and Node.js codebases. I've worked as a guest technical writer for Pusher and Bit, and I currently write on my blog. I love building dev tools and open-source software, and I have a habit of obsessing over documentation๐Ÿ™ˆ. Have a question? Email me or reach me on Twitter.