Presentation recording -- 'Best practices in API docs: Product overviews and getting started tutorials'
Video recording
Here’s the video recording:
Audio
If you want to listen to audio only, here’s the file:
Listen here:
Slides
Here are my slides:
(Note: Use both the right and down arrows to move through the slides.)
Presentation description
Here’s a description of the presentation:
Best practices in API docs: Product overviews and getting started tutorials
For new users, two of the most important topics in API docs are the product overview and getting started tutorial. These two topics combine conceptual understanding with hands-on exploration. Together, these topics can ground users in a good understanding of your product and the confidence to implement it.
However, both of these topics are challenging. The product overview requires solid understanding of the whole product, described succinctly and clearly. Its content can overlap with marketing content and often has both engineering and business executive audiences. The getting started tutorial requires writers to handle an intricate balance of information — keeping the instructions brief enough to fit the end-to-end scope but also detailed enough for the user to be successful. The getting started tutorial needs to give the user success in working the product; this confidence will inspire the user to more advanced levels.
In this presentation, you’ll learn best practices, pitfalls, and other strategies for these two content types. Templates for each content type will also be provided. Additionally, we’ll look at several examples and assess them based on more formal criteria.
Event details
(Note: The event is over.)
Date Oct 28, 2021
Time: 8am PDT
Presenter: Tom Johnson
Organizer: STC Washington, D.C.-Baltimore Chapter
Cost: $0-$15, Eventbrite
Related resources
I gave a similar presentation a couple of months earlier to tekom Europe. In the tekom Europe version, I didn’t have any examples and didn’t respond to audience chat during the presentation. But otherwise, the content is highly similar.
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.