The third API course from Peter Gruenbaum on Udemy
Peter Gruenbaum recently published a third course on writing API documentation on Udemy. I reviewed the other two courses in previous posts here and here. Peter’s third course is called The Art of API Documentation.
In general, this course is a little bit shorter than the others and focuses on how to create content for the non-reference topics in your documentation. Peter gets into topics such as tutorials, code samples, diagrams, and getting started sections. He explains how to use Postman, cURL, how to find open source projects to build your API documentation expertise, and more.
Overall, this course felt a little brief and seems mostly an overview to some of these topics. There’s a lot of depth that one could explore with more time. However, Peter does an excellent job in introducing you to the main concepts, topics, and components of non-reference API documentation.
I also really appreciated the focus on cURL and Postman. These two tools are essential when working with API documentation, and Peter includes exercises that dive into more detail with these tools.
Peter touched on a lot of different topics in the course. In going through the course, I found myself wanting to create a list that I could use to evaluate API documentation. Such a list might include questions like the following:
- Does the overview explain how and why I would want to use the API?
- Does the documentation provide code samples in the user’s target language?
- Can users easily copy and paste the code samples, and do they work on their own?
- Does the API documentation contain a getting started tutorial?
- How long does it take to complete the hello world tutorial and show some output?
Overall, the course will probably take you about an hour to complete. Peter’s voice and slides are easy to understand, and he follows a predictable pattern with each section. With each section, he provides a brief overview of the topics he will cover, he covers them, and then follows up with summary slides and explanation.
One component I thought Peter needed more information about was publishing tools. This may be because I simply like the tools aspect of documentation. I felt he should have talked about some REST API specifications such as Swagger, static site generators, browser-based platforms specifically designed for API documentation, and more. I know Peter has worked with a lot of different tools, and I’d love to hear his feedback about the best tools to use for API documentation projects.
That said, the discussion about tools does tend to derail the focus on the core subject matter content, which is API documentation content. The tool you end up using to document your API will likely already be established by your company — unless you’re working for a startup and defining the tools yourself. Additionally, the tools discussion tends to get too mired in technical details. As such, keeping the focus on the concepts is probably a good idea.
You can take The Art of API Documentation here. Use the code idrather for a 38% discount (which makes the course $24 instead of $39).
