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.
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.
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.
Let's do this!👊
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.