I'd Rather Be Writing Podcast Feed

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 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 most difficult part of adopting an API is at the beginning. If there is a learning cu

Best practices for API documentation -- podcast with Andrya Feinberg

I’m gave a webinar to the Southern Ontario STC on Monday, Feb 2. This post contains the slides and recording. Webinar description Survival strategies for API documentation If you’re documenting an API for the first time, you may be in survival mode just trying to decipher the code, unravel developer speak, and publish a coherent Continue Reading »

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 I'm gave a webinar to the Southern Ontario STC on Monday, Feb 2. This post contains the slides and recording. Webinar description Survival strategies for API documentation If you're documenting an API for the first time, you may be in survival mode just trying to decipher the code, unravel developer speak, and publish a coherent set of documentation. API documentation is a new landscape for most technical writers. Traditional platform APIs are often published through a document generator such as Javadoc or Doxygen, while REST or web APIs are published using everything from document generators that parse Swagger and RAML specs to custom toolsets to manually-formatted web pages either from static site generators (such as Nanoc) or homegrown sites. The reference documentation is actually the easy part. The real difficulty, and most likely the one you'll be tasked with, is showing developers how to use the API, the way the various endpoints or classes work together, and how you can piece it all together with the right parameters to achieve an actual business goal. In this presentation, I'll give you an introduction to API documentation, try to answer your questions, and give you tips for getting started in the right direction. For more details, see the STC Ontario site. Video recording http://youtu.be/I8rGe2w1sAo Slides Survival Strategies for API Documentation: Presentation to Southwestern Ontario STC chapter from Tom Johnson You can also download the slides in PowerPoint format. Audio Length: 60 min. Download MP3 (right-click and select Save As) The presentation is similar to the one I gave at TC Camp, which I recorded and made available here. However, this presentation is more compressed, lasting just one hour instead of two. Next: 2.0 Best practices for API documentation -- podcast with Andrya Feinberg

Survival strategies for API documentation -- slides and recording

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 I recently gave an API workshop at the TC Camp Unconference last weekend in Santa Clara, California. This post includes a video recording of my presentation, along with slides, audio, and workshop files. I actually prepared four separate slide decks for the workshop, but only used 2 and a half of them. I don't know why I prepared so much. In the back of my mind, I was thinking that I could just use all of this material for a udemy course or something, without realizing that it would be impossible to compress it only the fly into a two hour slot. At any rate, I'm providing all of the slide content here. If you have feedback of any kind, please let me know so I can improve with future workshops. Video recording http://youtu.be/0yfNd7tzH2Q This recording contains both the slides + audio for the full two hour workshop. I didn't edit this video, so you'll see some interruptions about wireless connectivity, parking, audience questions that are hard to hear, and more. Workshop files To get the workshop files, you can download them from Github here: github.com/tomjohnson1492/apiworkshop. Alternatively, if you want the slides + workshop files all in one download, grab it here: bit.ly/tomapiworkshop. Slides I uploaded my four slide decks to Slideshare because it makes it easier to view the slides online. You can also get the raw PowerPoint slides by downloading them via the bit.ly link in the previous section. Slideshare now has the ability to integrate video into slides, so I integrate the above youtube video at the end of two of them. API workshop: Introduction API workshop: Introduction to APIs (TC Camp) from Tom Johnson API workshop: Deep dive into REST APIs API Workshop: Deep dive into REST APIs from Tom Johnson API workshop: Deep dive into Javadoc API workshop: Deep dive into Java from Tom Johnson API workshop: Deep dive into code samples API Workshop: Deep dive into code samples from Tom Johnson Note that this slide deck is almost identical to a presentation I gave previously as a webinar to the soap! conference. You can see the slides + recording here. This recording provides a much better exploration of code samples than I gave during the TC Camp Unconference presentation. Audio only If you only want the MP3 file for the audio only (e.g., if you want to put it on your iPhone and listen on the go), you can listen to or grab the audio file here. Length: 127 min. Download MP3 (right-click and select Save As) Next: 1.9 Survival strategies for API documentation -- slides and recording

API workshop video + audio + slides + workshop files from TC Camp

The following is a recording of a presentation about passive versus reactive documentation by Greg Koberger, developer and designer for ReadMe.io, a slick new REST API documentation tool. Greg gave this presentation at the STC Silicon Valley chapter meeting on January 12, 2015 in Santa Clara, California. (He gave a similar presentation to a Write the Docs meetup group in San Francisco.) Length: 76 min. Download MP3 (right-click and select Save As) You can view the slides here. About Greg Koberger Gregory Koberger is the founder of ReadMe.io, which provides collaborative developer hubs for companies or projects. He has previously worked at Mozilla, Greylock, and numerous startups. You can learn more about Greg at gkoberger.net. You can explore ReadMe.io here: ReadMe.io Here's my brief summary of the presentation. Overview of doc levels Greg outlined three levels of documentation: Passive: Has no knowledge of the user. Reactive: Responds to an action from the user, such as something the user says or does. Proactive: Anticipates the user's needs and pushes the appropriate content to the user at the right time. Passive Passive documentation is documentation that could be contained inside a book. It is often produced by static site generators, and includes deliverables such as topical guides, tutorials, and reference material. Level 1.5: Passive(ish) example Moving a half a step beyond passive, examples such as forums, Q&A sites like Stack Overflow, and other community driven or collaboratively edited sites aren't totally passive, nor do they have completely static content. With a Q&A post on StackOverflow, for example, users are asking questions and getting responses from other users. (Greg noted that StackOverflow provides a compelling model for documentation. If someone searches for a technical answer and can't find it online, he or she asks the question so that the next time someone searches for the answer, it's available.) Why do docs need to be dynamic? Greg said that when you're building a website, on average a developer uses between 8-10 APIs. As a result, developers need to quickly get in and out of various documentation sites, finding code snippets to easily copy and paste, locating quick answers, etc. When people are traversing so many different APIs, they don't have time to read through tomes of documentation at a leisurely pace. Dynamic docs can help reduce the cognitive load on the user who is quickly looking for answers and code samples. One example is a section on authentication. Nearly every API doc includes this section, with a sample about how to pass your credentials or API token with REST calls. Why not have the user log in to the doc site, and then auto-populate code samples with his or her authentication credentials directly into the code samples dynamically, making it easier for the user to copy and paste the sample? This is one example of how to reduce cognitive load on the user. Level 2: Reactive doc With reactive documentation, you use what you know about your users to make their lives easier. Ideally, code samples and other information should be personalized with information pulled from the user's profile. For example, if you know what platform the user is on (based on profile information), you can dynamically filter the doc content. If the user's preferred language is PHP, your code snippets can default to the PHP tab instead of the Ruby tab, for example. Greg emphasized that code samples should be copy-and-pastable so they just work. Another example with reactive documentation might be an on-boarding tutorial. If you know details about the employee's location, role, and other details, then you can dynamically filter the on-boarding tasks to fit that profile. Error messages are another place to personalize and customize content. The errors themselves can contain variables that are personalized -- for example, instead of "Failed to instantiate module," if your company was ACME, the error message

The following is a recording of a presentation about passive versus reactive documentation by Greg Koberger, developer and designer for ReadMe.io, a slick new REST API documentation tool. Greg gave this presentation at the STC Silicon Valley chapter meeting on January 12, 2015 in Santa Clara, California. (He gave a similar presentation to a Write Continue Reading »

Moving from passive to reactive documentation -- recording of presentation by Greg Koberger, ReadMe.com founder

Length: 62 min. Download MP3 (right-click and select Save As) In this podcast, I talk with Mark Baker from Every Page Is Page One about unifying the API doc publishing toolchain. Here are some questions I ask Mark during the podcast: What kinds of API docs pose challenges with the tool chain? Do API reference Continue Reading »

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 Length: 62 min. Download MP3 (right-click and select Save As) In this podcast, I talk with Mark Baker from Every Page Is Page One about unifying the API doc publishing toolchain. Here are some questions I ask Mark during the podcast: What kinds of API docs pose challenges with the tool chain? Do API reference docs need to be separate from other docs? How do you integrate API reference with non-API reference info? How do you extract source code comments from Java or C++ and push them into another publishing chain? How can the structure of source-code comments be parsed and transformed into another format? Is there value in publishing Java API doc in a syntax familiar to Java developers (Javadoc)? same with C++ (Doxygen)? What are the best publishing strategies for REST API documentation? Is XML (as opposed to Markdown or some other format) the right markup for API doc? What are some limitations with DITA with respect to publishing API doc? What advantages does SPFE have for API documentation? What is a top-down architecture versus a bottom-up architecture? What do you mean by tightly coupled versus loosely coupled? What are your thoughts on single-page docs (such as parse) that load more content on scroll versus docs that separate out into multiple pages? Are there any API doc sites that you think serve as particularly good examples of how to do API documentation right? Can StackOverflow be considered API documentation? About Mark Baker Mark Baker is guru when it comes to publishing structured documentation on the web. He articulated his approach in a book titled Every Page Is Page One and even developed his own XML-based architecture called SPFE. He has a blog at EveryPageIsPageOne.com, where he provides thought leadership on best practices for technical communication, particularly in optimizing documentation for the web. Next: 1.8 API workshop video + audio + slides + workshop files from TC Camp

Podcast: Unifying the API doc publishing toolchain, with Mark Baker

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 Length: 40 min. Download MP3 (right-click and select Save As) In this podcast, Peter Gruenbaum talks about automating REST API documentation. Here are a few questions I asked Peter during the podcast: What do people mean when they use the term "automated documentation"? Is automated documentation preferable to manual documentation? Why is it more difficult to automate REST API documentation than it is with platform API documentation? What are some tools used to automate REST API documentation? How can Swagger, Enunciate, I/O docs, and some other tools be used to automate REST API documentation? What's your default go-to method for documenting a REST API? Are dynamic endpoint generators like Swagger helpful for developers in learning an API? Do automated documentation tools for REST reduce documentation drift? How do you integrate notes, code samples, and other information into an automated doc format like Swagger? Can you build a mock sample with Swagger without having a real API? Are videos popular with API documentation? Is API documentation only a good option if you love code? What API documentation course are you preparing for Udemy? About Peter Gruenbaum Peter Gruenbaum is a seasoned API writer with many years of experience providing technology learning solutions. He runs a company called SDK Bridge in Seattle that specializes in API and SDK documentation, video tutorials, sample code, and more. Here's more detail about Peter from SDK Bridge: Peter founded SDK Bridge, LLC to bring together his love of technology and writing. He has worked as an API writer to describe APIs for eCommerce, automobile traffic prediction, electric utilities, mobile phones, and tractors, just to name a few. At Red Llama, he created a program to teach creative technology classes to low-income youth to inspire them to consider technology careers, obtaining grant money from the Gates Foundation, Microsoft, and others. This program has now become the Software Development for Kids project at SDK Bridge. Peter received his BA in Physics from the University of Chicago and his PhD in Applied Physics from Stanford University. Next: 1.7 Podcast: Unifying the API doc publishing toolchain, with Mark Baker

Podcast: Automating REST API documentation, with Peter Gruenbaum