Developer documentation is a unique specialty within technical writing. Instead of writing for an audience of end users, you write for an audience of programmers. This is the most technical you can get when writing for software!

I have worked on several API documentation projects. An API (Application Programming Interface) is a set of methods or functions that programmers can call to access data in another system. Many, many products provide APIs these days, especially web-based products. For example, the popular note-taking service Evernote provides a web-based API that lets developers connect to the service and perform operations on a user’s notes. This is what makes the various third-party Evernote utilities and clients possible.

This Programmable Web directory gives a good sense of how common APIs have become.

API Documentation Deliverables

There are several types of deliverables appropriate for API documentation:

• Getting started topics. These topics introduce the API and provide basic information a developer would need to start working with the API. Topics often include installing the files you need to access the API, identifying any references you need to add to your project, and information about what files you might need to redistribute to end users. Other topics may include information about basic, required tasks such as establishing a connection to the system and authenticating a user.These topics can be in a full guide or in a help system. In my most recent API project, I created a short Getting Started Guide that covered many of these topics. I also included some common tasks in the full class reference, to take advantage of linking directly to the relevant classes and members.
• Code walk-through topics. A walk-through topic takes a common task and describes all the steps and code to accomplish that task. The topic should address possible pitfalls and make recommendations for the best way to accomplish the task, given the particular functionality and available methods in the API. Of course, the most important part of this type of topic is actual, working code.
• Class reference topics. These are the type of topics that many people mean when we say “API documentation” – the detailed reference topics for every class, method, property, enumeration, and so on. For a particular class or class member, these topics should:
  • Define the class or class member and provide the complete syntax.
  • Define method arguments and return values.
  • Explain the purpose or use of the class or class member and how it relates to data in the overall system. For example, are there any business rules around the data the class represents that a developer should know?
  • Include short code snippets that show how the item is used (depending on the complexity of the class or class member).

I have experience writing all of these types of topics. When I wrote API documentation, I owned all phases of the project: researching the API, writing reference topics, creating and testing code snippets to use within the topics, and creating code walk-throughs and getting started material.

I have created code samples for API documentation in C#, VisualBasic, and Javascript; I am currently learning Objective-C to add another option for future projects.

Why I Love API Documentation Projects

API documentation is one of my favorite types of documentation projects. This type of work is a terrific blend of the “technical” and the “writing”, as both aspects are vital to creating a useful deliverable for developers.

Researching the functionality of an API and creating effective code samples is an enjoyable challenge. In my projects, I created my own test application I could use as a sandbox to try out all the different methods. I used this to ensure that I fully understood how the methods worked; I was able to write authoritatively about how to use the methods because I tested them myself with my own code. I could then choose pieces of code that made sense to include in my topics as code snippets.

Does your company need a writer who will dive into your API, learn all about your product, work independently, and produce detailed, accurate API documentation? Contact me.