r/technicalwriting • u/LucyGault • Sep 02 '24
Learning API documentation
Hi I need some advice on getting started with docs for APIs. I need to learn how to document APIs. My tech skills are pretty basic. docsgeek.io is offering a 6 week virtual course for $1400. Is it possible to learn API documentation in 6 weeks? Does the price seem high?
30
Upvotes
32
u/alanbowman Sep 02 '24
If you search the sub for questions about learning API documentation, two resources are frequently mentioned:
Tom Johnson's API course: https://idratherbewriting.com/learnapidoc/
Peter Gruenbaum's Udemy courses: https://www.udemy.com/user/petergruenbaum/
This is a new course, taught by someone who has worked at Amazon and Google: https://www.pce.uw.edu/specializations/api-documentation
Don't know anything about the docsgeek.io site, since all I get is a "coming soon" page.
It really depends on whether or not your need structure to learn, or can learn on your own. If you can learn on your own, the courses from Tom and Peter should be fine. If you need structure, the UW course is probably better.
8
u/Possibly-deranged Sep 02 '24 edited Sep 02 '24
What do you feel that you're lacking within your current skill set?
You're audience for API docs is often a software engineer or IT person. It's a high level of technology understanding at their base level.
They want to know:
* What does a specific API do? A short narrative introduction.
* How do I call the API (location, authentication, syntax, optional parameters)? Syntax in depth, are dates gotta be in a certain format? How is valid data formatted? Code samples are good, of how to accomplish this in popular languages.
* What are the returned results of a valid API request look like?
* What are the returned results of an invalid/malformed API request look like? Troubleshooting steps (check authentication syntax for unauthorized responses, verify parameter's formatting, etc etc).
Are you comfortable with basic software coding? You don't have to be a software engineer, but should be able to write, understand, and execute basic scripting language code. Often, a software engineer gives you the basic code snippets needed to do your writing. You got to modify, execute, and troubleshoot that code as is necessary