Information Development World and the Customer Experience — A Podcast with Scott Abel and Val Swisher


Length: 26 min. Download MP3 (right-click and select Save As) In this podcast, I talk with Scott Abel and Val Swisher, organizers for the Information Development World conference, about the technical writer’s role in the customer experience. The customer experience is a major focus of the Information Development World conference. The Information Development World conference Continue Reading »

Introduction to API documentation: Interview with Scot Marvin


Length: 30 min. Download MP3 (right-click and select Save As) In this podcast, I talk with Scot Marvin, an API technical writer based in Oregon, about some introductory topics with API documentation. Topics covered in the podcast include the following: The prevalence of APIs 15 years ago compared to today The definition of an API Continue Reading »

Started a new job


I started a new job last Monday at a company called The 41st Parameter in San Jose. I’m pretty excited about it. 41st’s main product helps prevent online fraud with transactions; another product helps with identity resolution for advertising technologies. I’ll be creating developer documentation for products that include C++, Java, .NET, and REST. I’ll Continue Reading »

Lessons learned as a novice API technical writer — Interview with Mary Linderman (podcast)


Length: 30 min. Download MP3 (right-click and select Save As) In this podcast, I talk with Mary Linderman, a technical writer in Chicago who has been doing API documentation for the past couple of years, about her experiences in the API documentation space. Mary recently wrote an article called “Lessons learned from a novice API Continue Reading »

Creating code samples for API/SDK documentation (webinar recording, slides, and audio)


Yesterday I gave a presentation to the soap! conference group on creating code samples. Here’s the video recording: And the slides: Here’s a link to the PowerPoint file: zip file | pptx file. And here’s just the audio. (Note that the audio here is crisper than the audio in the video.) Your browser does not Continue Reading »

Recording of my STC Sacramento presentation — Why users can’t find answers in help material


A few months ago I gave a presentation to the STC Sacramento chapter on findability of help content. The recording is available here: Your browser does not support the audio element. Download MP3 (right-click, then Save Link As) Here’s a link to the slides and other material: PowerPoint slides zip file | pptx | slideshare Continue Reading »

Complex tools versus simple tools


Neal Kaplan’s post on the Death of Technical Writing, which focuses heavily on comparing complex tools versus simple tools, has caught the attention of the tech comm world in a viral way. The comment thread on the post has some of the best insights I’ve seen. A couple of months ago I posted about a Continue Reading »

DITA: Nested subheadings and the concept element


5/11/2014 update: I updated this post with more accurate information, particularly about nesting concepts within concepts. When you’re writing concept topics, at times you may need a third level subheading. Usually the article title is the first level, your main subsections are your second level, and sections within the subsections are third levels. These correspond Continue Reading »

DITA: Limitations with the chunk=”to-content” attribute in relationship tables


Updated 5/11/2014. DITA has a lot of powerful ways to combine different topics through ditamaps. Although DITA’s architecture encourages a lot of little pieces of content, you can bring these pieces together into articles of more substance. By having smaller chunks of information, you have more capability for re-use into various combinations and outputs. Here’s Continue Reading »

DITA hierarchical links, related links, short descriptions, and one-folder organization


I’m continuing with my series about DITA. In this post, I explain parent-child page links, content re-use when the content exists in different elements, a one-folder-for-all-files organization, and a better workaround to transferring relative links to Drupal. Short descriptions and parent-child pages When you arrange pages hierarchically, the parent pages (that is, pages that have Continue Reading »