Adobe FrameMaker

Get new posts delivered straight to your inbox.

Subscriber count: 4,300

Stitcher radio

Adobe FrameMaker

The third API course from Peter Gruenbaum on Udemy

Feb 8, 2016 • api-doc

Peter Gruenbaum's third API documentation course is now available on Udemy. This course covers topics in API documentation outside of reference material, such as tutorials and overview sections. This course will expose you to the many different needs in API documentation, and is a course I recommend even though it is briefer than Peter's other courses.

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.

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).

follow us in feedly

Get new posts delivered straight to your inbox.

Subscriber count: 4,300

About Tom Johnson

Tom Johnson

I'm a technical writer based in the California San Francisco Bay area. Topics I write about on this blog include the following technical communication topics: Swagger, agile, trends, learning, plain language, quick reference guides, tech comm careers, and certificate programs. I'm interested in information design, API documentation, visual communication, information architecture and findability, and more. If you're a professional or aspiring technical writer, be sure to subscribe to email updates using the form above. You can learn more about me here. You can also contact me with questions.