Document the API

A presentation at Australian Society for Technical Communication Annual Conference 2018 in in Gold Coast QLD, Australia by Alec Clews

More and more software companies today provide, not just software products, but Application Programming Interfaces (APIs) as well. They do this to encourage customers and partners to connect the software product to other software systems. As more and more software is moved to the cloud, these connections between systems become vital to the customers who want to use your product.

Documenting APIs is, in many ways, similar to creating product documentation. But there are also some important differences and this talk briefly discusses these issues for technical writers who have not documented APIs before.

Alec Clews provides an introduction to creating effective API documentation for technical writers who have only written product or user manuals.


  1. What is an API and the different types of API?
  2. Why are APIs important?
  3. Who is the audience for API documentation?
  4. What does this audience need from technical documentation?
  5. What should we include in API docs?
  6. How can we make our writing lives easier? What tools can we use?
  7. The role of API Doc tools like Swagger.
  8. How does API documentation support the organisation's marketing message?

No prior technical knowledge is assumed, this talk is suitable for novices and anyone who has never documented an API before.


The following resources were mentioned during the presentation or are useful additional information.