JSON tutorial in Java

API Documentation and Why You Should Never Write Your Own

Print Friendly, PDF & Email

API Documentation – Why You Should Never Write Your Own

If you’re a developer, you know how good your app is and how dead-easy-and-simple it is to use. So, sometimes, it’s hard to understand why other developers don’t seem to pick up on your API right away. Well, the reason why is probably a lot simpler than you think. Possible cause and problem? Your API documentation might suck.

Don’t get me wrong; developers are — usually anyway — a really smart sort and have brains and great ideas for days. Still, just because you can code a killer app, doesn’t mean you should write its API documentation. In fact, most really good coders suck at writing documentation (I did say “most” so disregard if this does not apply to you.) Why? They already know everything there is to know about their app or platform and expect everyone else to know just as much in no time at all. Well, the truth is other developers know nothing about your app (at the start) and probably need a little hand-holding to get started.

API documentation – Pros vs. Noobs

That’s where a professional API documentation specialist comes in (like that? I just made it up.) Someone like me, who understands the nuances of explaining an API but still knows what all the curly brackets, angle brackets, bars, circles, triangles and everything else means.

Writing API documentation is not exceedingly difficult, but it’s not as easy as some people make it out to be either. Sure, popping a table into a document and filling it with some words is easy enough. But, will readers be able to understand those words easily and quickly enough to dive into your API before getting frustrated and abandoning it.

You could also use structured data to create your documentation – if you want to cheat. I mean, machine-generated documentation isn’t so awful I suppose, but it’s not really user-friendly either. If you want great API doc, you need a real writer-human-person-nerd to produce it.

When it’s all said and done, nobody knows your app like you do. Nevertheless, unless you’re the rare exception, creating documentation for your API yourself may be a pursuit in futility or even insanity. At the end of the day, you should leave the API doc creation to a pro, noob!

A professional API doc “person” (plenty of API goddesses out there these days) can help you create documentation that is easy-to-follow and well formatted. If you want developers to help grow your app user base with cool plugins, extensions and companion apps, getting them up and running with your API — as fast as possible — is essential.

Anyway, that’s enough ranting for today I suppose. If you want great API documentation for your project, call a pro (I am available to take your money also, by the way.) I think that’s enough for now. Oh, except that since you’re here, you should watch my little plug for hiring me to write your API docs. That is all. Peace out and, as always, thanks for stopping by.

Have a wonderful day!

Leave a Comment

Your email address will not be published. Required fields are marked *

For security, use of Google's reCAPTCHA service is required which is subject to the Google Privacy Policy and Terms of Use.

If you agree to these terms, please click here.

This site uses Akismet to reduce spam. Learn how your comment data is processed.