API documentation podcasts 1.0 Creating code samples for API/SDK documentation (webinar recording, slides, and audio) 1.3 API Doc presentation slides and recording (San Francisco STC chapter) 1.4 Getting a job in API documentation: Podcast with Andrew Davis 1.5 Learning how developers think, and other API doc insights: Podcast with Joe Malin 1.6 Podcast: Automating REST API documentation, with Peter Gruenbaum 1.7 Podcast: Unifying the API doc publishing toolchain, with Mark Baker 1.8 API workshop video + audio + slides + workshop files from TC Camp 1.9 Survival strategies for API documentation -- slides and recording 2.0 → Best practices for API documentation -- podcast with Andrya Feinberg 2.1 Recording of API documentation workshop (REST and Javadoc) at tcworld India 2015 2.2 API Documentation presentation to East Bay STC chapter -- slides and recording I recently talked with Andrya Feinberg, a documentation manager and content strategist for Emotient, about best practices with API documentation. Below is a writeup Andrya has provided that summarizes some of the points she makes in the podcast. Length: 42 min. Download MP3 (right-click and select Save As) Here is Andrya's summary of the best practices: API Documentation Best Practices, by Andrya Feinberg In the world of Technical Communication, Content Strategy, User Assistance, Information Architecture, and User Experience, there have always been best practices and industry standards. Each type of content, independent of which industry you are in, has its own set of rules, a style guide, and a terminology usage guide. I live and breathe best practices and industry standards. Why? This is what helps me to create content that is easy to use, easy to read, easy to understand, and minimal. There's nothing more appealing than content that is simple, clean, and gives you exactly what you want. When I created my survey on API documentation, I put myself in the user's shoes, as we should always do, and I wanted to make sure that I performed an exhaustive audience analysis. Why would I put myself in the user's shoes and create content solely focused on the user's needs? Creating content for a specific user is what it's all about, and I can't emphasize this enough. It's my passion and my purpose. People don't have time to read through a sea of text to find the information they need. We are in a hurry and have a task in mind. At that exact time, we must find exactly what we're looking for. If we don't, we are left irritated and frustrated and must go somewhere else to find the answer. I know that if I have to spend more than two minutes looking for what I need, I get a tad bit irritated. Okay, probably more than a tad, but you get the idea. Every user has expectations, and it is the technical communicator's purpose and goal to not only meet the user's expectations but to exceed them. Make this your priority and your focus, and your users will thank you over and over again. Here are the best practices for API documentation. These came directly from the responses that I received from engineers and developers that spend their lives in APIs with API documentation. Create content that is easy to use, read, and understand. Create an exhaustive and concise plan for API documentation. Make sure that you talk to all of your SMEs, engineers, and developers to create what they need and what they want. Keep related topics together. Focus on how you can provide the right information to the right user at the right time. Make sure that the content is consistent and accurate. Don't leave anything out, such as missing segments or examples of code. This is all levels of wrong! Leaving out part of a command or a call leaves users frustrated and irritated. What's worse is that they can't use (and don't trust) the API! Make sure that the documentation reflects the way that the API works. Include an 'overview' or an 'introduction' Put this at the very beginning. Think of this as the 'landing page'. The