This guest blog post was written by Jana Pospichal Cromer, a technical writer for 20+ years, who loves taking super complex concepts and distilling them into something the average human can understand. Jana embraces the more technical aspects of tech writing, including API documentation, and revels in the science-y and nerdy side of her current assignments in dairy tech.

 

If you've written for a software company in the last 10 years, there's a good chance you've been tasked to create API documentation to support your dev team. Perhaps you quickly realized that this type of technical writing is way too technical and out of your league. Maybe you found your true technical documentation love

I landed somewhere in the middle. I've always been on the more technical side of the tech writer spectrum, dabbling with web design and even an e-commerce site or two back when that kinda thing was new. (Yeah, I know I'm dating myself here!) But I figured if anyone should be able to learn how to document an API, I was a decent candidate — and even I had a love-hate relationship with APIs at the start!

How to Document APIs

If you're determined to learn about APIs and start documenting them, check out my tips and suggestions. Who knows? Maybe an API crush is in your future! 😍

Start by Exploring

I learned a ton from the free(!) and incredibly helpful online training Tom Johnson created at his website: idratherbewriting.com. Be sure to check out the full-length training here, and definitely buy him a coffee here

Thanks for all that you do for the tech writing community, Tom — you're a rockstar!! As part of the training, Tom walks you through some great API document samples. The gold standard is Stripe, and he points to many others in his training as well.

Be sure to go beyond the training course and check out what other players in your industry or even your competitors have out there for their APIs. Is it easy to use? Do they have nicely-formatted code and thorough explanations? A Getting Started section? How about errors — do they spell those out?

Learn the Tools

Next, talk to your tech writing network or developers and see which documentation tools they use to interact with their API — and get started. It might be a little intimidating at first, but you can do it! A free and user-friendly API development and testing tool I recommend is Postman.

You will need help from your dev team to gain access (credentials for authentication, connection and URL details to communicate with your API), but if they know you'll be taking care of the technical documentation, they should be more than willing to help! Most developers don't like having to document their tools and should be excited to have an actual technical writer willing to handle the API document for them.

Interact with Your API

Take the time to review and get comfortable with your API and the code that comes along with communicating with your API. Send requests and receive responses from your API like your developer audience would. Code samples are the bread and butter of writing API documentation, so make sure you have a way to get the code sample on your own. You've got this!

As you become more and more familiar with the types of requests and responses your API supports, the responses, what to include in a request, etc., everything will start to make more sense. Be patient and ask for help when you need it.  

Understand Your Audience

API documentation needs to be a one-stop-shop for all potential readers. Ask yourself:

  • Does it provide a high-level explanation of the API reference to explain its purpose to potential partners and decision-makers? Think CEOs, CTOs, and integration product managers who need a general understanding of what your API does and if it would work for their customer base and with their product. 
  • Does it dig deep into the weeds and explain the details of each data point and all potential errors for the developer who needs that info? Be sure to keep the content easy to understand and straightforward, explaining the system and data for someone new to your industry or even to software development. Avoid jargon, spell out acronyms, and be kind to your readers!   
  • Is your delivery format searchable and easy to understand for everyone? Get input from your dev team, your leadership team, maybe even your mom — everyone should be able to grasp the concepts you're presenting!  

Flex your Documentation Tool

Depending on your API documentation tool and how you're planning to publish your help, be sure to take advantage of available features to help you with automation, content reuse, and single sourcing. We went with MadCap Flare and haven't looked back! 

Be sure to check out the Using MadCap Flare to Generate API Documentation webinar to see how we used Flare at VAS to document our API!

Keep your Docs Current

Last, but definitely not least! Nothing makes readers ditch API documentation faster than finding that your docs are outdated. Great API documentation requires keeping tabs on the latest API additions and sharing the latest updates with your readers using a high-level What's New section.  

Good luck on your API documentation journey — I hope you find your true technical writing love with APIs or wherever it takes you!