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 from programming language into something the average human can understand with using an API documentation tool. 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 using internal documentation tools. 

Key Takeaways:

  • Start by exploring the API tools that are available out there that have the best documentation, the best UAnd I and features, and are in your price range.
  • Learn the tools with help from their online documentation. Talk with tech writers and developers and see which api documentation tools they use to interact with their API.
  • Review your API. Become familiar with the responses and which requisites your API supports.
  • Understand your audience, and think of how anyone from a CEO or CTO to a product manager. Be sure to focus on the benefits to their customer base to help them understand your cause.
  • Utilize all aspects of your API tool and make sure you are maximizing features and capabilities to make your workflow efficient.
  • Make sure to keep documentation up-to-date, which can be achieved using a solution, such as MadCap Software!

If you've written for a software company in the last 10 years, there's a good chance you've been tasked with creating 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 use API documentation tools, I was a decent candidate — and even I had a love-hate relationship with APIs at the start!

How to Document APIs

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 the Stripe API documentation tool, 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 api 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 and create good documentation.

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 and create some good api documentation. 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 API Documentation Tool

Depending on your API tool and how you're planning to publish your help, be sure to take advantage of available features to help you with automation, interactive documentation, content reuse, and single sourcing. We went with the software documentation tool 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. An API documentation generator is sure to keep your documents up to date. 

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

If you're interested to know more about technical documentation software, checkout Madcap Flare today!