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
A Coder’s Guide to Writing API Documentation
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.
Alternatives to Swagger for documenting REST APIs? – Quora
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.
Creating API Documentation – Stack Overflow
How to Write “Good” API Documentation
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.
How to Write Object-oriented API Documentation
First of all, a good API design facilitates understanding, so do good names (class names, method names, parameter names) (I recommend [12] 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.
Learn API Technical Writing: JSON and XML for Writers
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 .
Why We Write API Documentation
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.
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.
API Blueprint – API Documentation with tools
Doxygen – create API documentation from source code
ReadMe.io / Example API Documentation
API Security and Usability
Create your first API | Apigee
REST
Standard methods for documenting a RESTful API – Stack Overflow
REST API Documentation Best Practices