Learning API Documentation
What is API Documentation? Well, you can read about it in my article: ‘What is API Documentation’.
Now it’s time to learn how to write it, so I gathered courses on learning API documentation that will also provide you with background information on APIs and structured data that help you upgrade your skills.
Learn API Technical Writing
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.
By the end of the course, you will understand what APIs are, why they are important, and how to read and document structured data. In this course you’ll find:
- Eight videos that:
-Provide background information on APIs and structured data
-Break down sample JSON and XML files to show you how they work
-Show real-time, narrated writing of JSON and XML documentation
-Four hands-on exercises to lead you through building and documenting JSON and XML files
- Two text-based lectures about useful software tools
- Five short quizzes to keep you on your toes
- PowerPoint presentations as a resource for every video lecture
Learn API Technical Writing — REST for Writers
This is the second in a series of courses for technical writers who want to learn how to write API documentation. The first course is called “Learn API Technical Writing: JSON and XML for Writers”, and it is recommended that you first take that course, unless you are very familiar with JSON and XML, and how to document them.
This course teaches how to document REST APIs. No programming experience is required, but technical writers with programming experience who want to know more about REST APIs will still find it useful.
By the end of the course, you will understand what REST is and how to read and document REST requests and responses. In this course you’ll find:
- 12 videos that:
-Provide background information on REST APIs
-Break down REST requests into their various pieces with examples
-Show real-time narrated writing of REST documentation
-Provide overviews of authentication and authorization for REST
- 7 hands-on exercises to lead you through making and documenting REST requests
- 7 short quizzes to keep you on your toes
- PowerPoint presentations as a resource for every video lecture
- A Microsoft Word document you can use as a template for REST reference material
The Art of API Documentation
This is the third in a series of courses for technical writers who want to learn how to write API documentation. The first two courses are called “Learn API Technical Writing: JSON and XML for Writers” and “Learn API Technical Writing: REST for Writers”, and it’s recommended that you first take those courses unless you are very familiar with API documentation, and how to document reference material.
This course teaches how to write conceptual API documentation, such as overviews, getting started sections, and tutorials. For the most part, no programming experience is required, but technical writers with programming experience will still find it useful.
In addition to conceptual material, this course covers guidelines for good sample code, tools for making REST requests, and how to find an open source project to document as a way to get into the field of API writing.
By the end of the course, you will understand how to write good API conceptual material, how to make REST calls using GUI and command-line tools, and how to find an open source project to document. In this course you’ll find:
- 8 videos that:
-Describe how to write good conceptual material
-Provide guidelines for good sample code
-Demonstrates how to use tools to make REST calls
-Leads you through examples of how to find open source projects on the internet
- 2 hands-on exercises to lead you through making REST requests using tools
- PowerPoint presentations as a resource for every video lecture
- A PDF with resources for finding open source projects
Documenting APIs
Tom Johnson of I’d Rather Be Writing also has a good course on API documentation. In this course on writing documentation for REST APIs, instead of just talking about abstract concepts, Tom contextualize REST APIs with a direct, hands-on approach. You’ll first learn about API documentation by using a simple weather API to put a weather forecast on your site.
As you use the API, you’ll learn about endpoints, parameters, data types, authentication, curl, JSON, the command line, Chrome’s Developer Console, JavaScript, and more. The idea is that rather than learning about these concepts independent of any context, you learn them by immersing yourself in a real scenario while using an API. Immersion in real scenarios makes these tools and technologies more meaningful.
You’ll then transition into standards, tools, and specifications for REST APIs. You’ll learn about the required sections in API documentation, analyze examples of REST API documentation from various companies, learn how to join an open-source project to get experience, and more.
I hope you find these courses helpful!
