My DITA quick reference guide (QRG)


My DITA quick reference guide, or DITA QRG, is available on my menu bar and here: This DITA QRG consists of my own notes for working with DITA. Why create this quick reference guide? There’s a lot to know about DITA. If you look at the DITA 1.2 spec there are many, many elements Continue Reading »

Strategies for content re-use in Confluence


I’ve been knee-deep in Atlassian Confluence lately, analyzing the best way to re-use content. In this post, I’ll describe a fictitious scenario that resembles an advanced content re-use situation and then explore various strategies for re-use. The scenario Suppose you’re creating a bicycle manual for a Trek 7.3 FX (which happens to be the exact bike I recently bought). Continue Reading »

10 technical writing principles to live by

Image by James Butler (Flickr)

As I started my new job, I’ve been thinking about the most important technical writing principles I’ve learned in the past. The following are 10 principles to live by when doing technical writing. 1. Always test out the instructions yourself. Unless you can walk through the instructions and perform the tasks yourself, it will be Continue Reading »

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 »