Writers needed for Intercom issue on API documentation

I'm guest editing an edition of Intercom that will focus on API documentation (with a planned publication date of September 2014). As guest editor, I need to gather a handful of articles from tech writers with experience in this field. Are you interested in writing an article on API documentation? I have about 8 different topics I hope to cover. See this Google doc for details. If you're interested, add your name to the table below the to...

A simple way to write, edit, and publish documentation online using Google Docs and Markdown

If you work for a small company (for example, a startup with just a few tech writers), and only need to publish content online, you can forego expensive writing tools and processes and use a much simpler method to write, edit, and publish your technical content. In a nutshell, the method I describe here involves using Markdown syntax in Google docs to write and edit content, and then leverages stackedit.io to convert the content to HTML b...

How can we know something that is totally unfamiliar to us?

I've been reading some science books lately and visiting a few museums. These experiences have led me to the following question: How can we know something that is totally unfamiliar to us, such that we've never experienced or conceptualized it in the least degree before? This question is more philosophical than practical, but it does play a part in our role as technical writers. To consider the whole scenario of the unknown, think of some...

An argument for complexity rather than simplicity in technical communication

I am rarely impressed by mission statements, but I find the first paragraph of the recent reformulation of STC's mission statement refreshing. It defines the practice of technical communication as "the discipline of transforming complex information into usable content for products, processes, and services" (President's Midterm Report). The mission statement does continue on to address other less interesting topics, but that's beyond my co...

Gamification and user engagement in e-learning and documentation

For the past year I've been working at a gamification startup company called Badgeville in Silicon Valley. Badgeville is one of a handful of companies specializing in “gamification.” When you gamify an application, you integrate game elements into non-game contexts to better engage your users. If done right, gamifying an application can increase the engagement of your users by up to 48%, compared to only 28% for those who don't use gamifi...

Will structure and style make documentation processes less costly?

A reader writes, Let me start by saying that I am a huge fan! I've been following your blog for many years and together with Mark Baker's and Scriptorium blogs, you've taught me 90% of everything I know about tech comm and documentation. The problem at hand: Documentation for our biggest product has grown enormous over the years. The growth was organic, as more and more features and complexity was added. Our online help for the product cu...

Growing trends for APIs and my favorite resources to learn technical information

While riding home on the train today, I was thinking about directions I want to take my career. I actually don't have any presentations pending, no expected slides or research due (other than an article on gamification). As I thought about it, I realized that I want to dive more deeply into API documentation. The response to the API Workshop I'm helping organize has been really encouraging. Already we have 45 people signed up (with a cap ...

Upcoming interviews at the Intelligent Content Conference

Several years ago, at the STC Summit in Dallas, I took my video camera along and recorded about a dozen different interviews with presenters and other interesting people. Together, the videos had a total of 7,304 views. (You can see the full list of videos here.) This year, I'm going to be interviewing people at the Intelligent Content Conference in San Jose, California, February 26-28. The 2014 Intelligent Content Conference The Intelli...

Why I left the Mormon church

I joined the LDS Church in 1991 and stayed an active member until January 2014. I held many leadership callings, served a mission, graduated from BYU, and worked in the Church’s IT department for 5 years. What led me astray after being so consistent and believing for so many years? First, I want to define my audience. I am aware that many of those who leave the LDS or Mormon Church write bitter why-I-left stories. These stories contrast with...

Single-page docs versus "Click Insanity"

Check out this presentation by Brandon Philips at the 2013 Write the Docs conference. In the video, Philips argues for "single-page docs," which are entire help systems rendered on a single page. He says that for many technical information sets, like APIs, having all the functions, classes, etc. appear on the same page reduces "click insanity" and allows developers to more easily find what they're looking for. ">See the full list of 20...

Upcoming presentation to Sacramento STC Chapter on Jan 16

I'm presenting to the Sacramento STC chapter on January 16, 2014. It's a similar presentation I've given to the Berkeley and Silicon Valley chapters. You can view past recordings, slides, and other resources here. Now that this is the third presentation, though, I have changed this presentation a bit. I'm really reworking the first point about information fragmentation. I sort of took a lot of heat at the Berkeley chapter for my preferen...

Tips for writing code comments in developer documentation

I used Grammarly's proofreading software because my eyes become blind to errors after I read through the same post several times. When you write documentation for programming code, such as APIs and SDKs, you become accustomed to writing and editing code comments. Code comments are explanatory text mixed with programming code to explain what's going on in the code. For example, here might be a code comment for a JavaScript function: </p> ...

Recording of STC Berkeley presentation on why users can't find answers in help

Listen here: A few weeks ago I gave a presentation to the STC Berkeley chapter on findability of help content. The recording is available here: For the slides, see Recording and slides for why users can't find answers in help. The link refers to the Silicon Valley chapter presentation of the same material -- the slides are the same, but the presentation to the Berkeley chapter (this recording) differed quite a bit given...

DITA's output does not require separation of tasks from concepts

One of the main challenges to embracing DITA is accepting the idea that tasks and concepts should be separated. However, despite the common assumption that concepts and tasks should live separately when you follow DITA, actually it's not the case. You can combine concepts and tasks in DITA's output through your ditamap. Additionally, you can even combine concepts and a single task in a "general task" dita topic. Tasks versus concepts Pret...

The appeal of DITA

For about the past 6 months, I've been using Markdown syntax as a quick way to convert content to HTML and publish on Drupal, which is where we publish our help. But lately I've been feeling the pain of this process. Markdown is a lightweight markup somewhat like a wiki syntax. Any time I needed to do something more, like prepare a collection of more than 5+ files to publish at once, with cross-references between them, it's been a chore ...