{"API Evangelist"}

What to Include in API Reference Documentation

This post comes from the SDK Bridge newsletter.  I find so much value from what Peter and Jonathan do over at SDK Bridge, I asked them if I could repost their newsletter here and share with all of you.

This article presents a series of questions that your writing should answer for each type of element you would typically find in reference documentation.

To begin with, think about what a new user needs to know. If you can write for a new user, then you'll cover everything that an existing user will need to know. Once you have that mindset, answer the questions below. For a given element, some of the answers will be obvious from the context and not need to be documented, so use your judgment. In general:

For classes or structures:

For methods or functions:

For constants or enumerations:

For Web API requests:

If your company has an existing writing team, then the team will likely already have templates or guidelines for API reference documentation that address many of the issues discussed in this article. Just remember that the mindset of the people using your documentation is going to be a bit different that the mindset of the people designing or implementing the API. As a writer, you will need to translate between the two. If you keep these things in mind, it will be easier to write accessible and useable documentation.

If you don't know who SDK Bridge is, they provide API and SDK documentation services, that will truly help developers understand how to build on top of your API. You can find more information about them at the SDK Bridge website.