Enormous impact, thinking about how people learn, variety, and getting to work with cutting-edge technology – it’s pretty cool being an API writer these days. Of course, you have to love to write and you have to love to program. But if you are good at those two things, there’s never been a better time to be an API writer.
Want to write API documentation but don’t know where to start? Fear not, my friend. We’ve hunted down some of the best links to help you start writing your first set of API documents.
How to write API documentation
Writing documentation is a different form of writing than most people have experience with. Technical writing is an art that doesn’t come naturally. Writing documentation will start you down the road to being a better technical writer, which is a useful skill to have as a programmer.
This article is a guide on how to write API documentation. I’ll describe the most important components of API documentation and provide some suggestions about how to make it effective. I’ll also give you some hints for creating good overviews, sample code and reference material, including where you should focus your time and attention to get the best effect.
Nine very detailed answers to this on Quora.
This guide documents the Ruby on Rails API documentation guidelines.
After reading this guide, you will know:
- How to write effective prose for documentation purposes.
- Style guidelines for documenting different kinds of Ruby code.
After you finish the documentation, ask a friend or two to proof-read your document because what makes sense to you will not always make sense to your neighbor. If possible, ask someone who is unfamiliar with the application. This will give you the best possible feedback because they are going to be most similar to your user in terms of application knowledge.
First of all, a good API design facilitates understanding, so do good names (class names, method names, parameter names) (I recommend  for in-depth discussion about API design and API naming).
Then, the first fule is (R1) every sentence of the API documentation should contain some value by giving additional pieces of information. If the documentation only copies or rephrases the element name (whether class, method or parameter name), it has a an added-value of zero, it is simply wasted time for the writer and for the reader.
Video – This is the first in a series of courses for technical writers who want to learn how to write API documentation. This course teaches how to document structured data, focusing on the two most popular structured data formats: JSON and XML. If you are new to API documentation, this is a great place to start. No programming experience is required, but technical writers with programming experience who want to know more about structured data will still find it useful.
API documentation is a deliverable of a technical writer which describes, with examples, how to effectively use a Software, Hardware or Web API. It requires a thorough understanding of the API, its arguments, its return type and the languages and interface it supports. Technical Writers with programming knowledge often create instructions, procedures and example for APIs that is delivered along with software .
From Sarah Maddox at Atlassian.
API documentation tools
You don’t have to document the APis by hand. There are some interesting tools out there, many open source, that should help you with the presentation, format, and delivery of the API documents.