You are here

idratherbewriting.com

Post a note under our blog aggregation requests if you want your blog added to our aggregator. Please provide the RSS feed URL and the title of your blog.

Subscribe to idratherbewriting.com feed
Updated: 1 hour 35 min ago

Reviewing draft DITA content with subject matter experts: 6 essential points

Thu, 07/31/2014 - 10:51

Lately I have been exploring different ways to let subject matter experts review DITA content. In a previous post, I explored using easyDITA to facilitate the review. In this post, I’ll explore OxygenXML’s Webhelp with Feedback output for conducting the reviews.

What makes for a good review process?

By far the best review method I’ve (more)

My DITA quick reference guide (QRG)

Wed, 07/30/2014 - 11:18

My DITA quick reference guide, or DITA QRG, is available on my menu bar and here: http://idratherbewriting.com/ditaqrg/. This DITA QRG consists of my own notes for working with DITA.

My DITA quick reference guide

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 el (more)

Book Review: The Goldfinch, by Donna Tartt

Sun, 07/27/2014 - 12:27

I don’t often review fiction on this site because I made a decision long ago to brand this site as being specifically about tech comm. But a couple of recent posts by my blogging friends (Neil Kaplan and Sarah Maddox) remind me that it’s good to show more than one side of a person. I wouldn’t want you to thin (more)

Writing documentation in an interactive world: Some thoughts on using easyDITA and OxygenXML

Fri, 07/25/2014 - 03:32

Since moving to DITA, I’ve tried to settle on best practices and determine the authoring method that works best for me. I started out using OxygenXML, which is one of the most popular DITA editors. I like OxygenXML because it’s easy to work with the code. OxygenXML knows when to show you a list of all possible elements or values you can insert in your topic at any time.

For example, if you type <note type=", the editor prompts you with values you can choose from.

(more)

Content Re-use is so much better with DITA (and esp. with OxygenXML)

Sun, 06/29/2014 - 23:41

After my last post on content re-use strategies with Confluence, I realized that while you can do re-use with Confluence, you have to rely on so many third-party plugins, the whole solution tends to feel cobbled together with string and glue. While I initially thought Confluence would simplify authoring and allow me to focus more on content, the primitive re-use capabilities actually make help authoring more tedious and time consuming.

The real deal-killer with Confluence is managing a (more)

Strategies for content re-use in Confluence

Tue, 06/24/2014 - 11:15

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). There’s a 7.1 FX and 7.2 FX model for the Trek bike, which you’re also creating online manuals for.

Additionally, the (more)

The part of the brain you should listen to when writing

Sun, 06/22/2014 - 18:01

In This is your brain on writing, Carl Zimmer writes:

A novelist scrawling away in a notebook in seclusion may not seem to have much in common with an NBA player doing a reverse layup on a basketball court before a screaming crowd. But if you could peer inside their heads, you might see some striking similarities in how their brains were churning.

The article caught my att (more)

10 technical writing principles to live by

Fri, 06/20/2014 - 10:33

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 difficult to evaluate the help material. Testing the instructions seems like a given, and with GUI documentation, it usually is. But in reality, it can be complicated to do this. You may need to set up a special server environment or scenario. The informa (more)

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

Thu, 06/19/2014 - 00:10

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 Informat (more)

Introduction to API documentation: Interview with Scot Marvin

Mon, 06/16/2014 - 11:18

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 AP (more)

Started a new job

Thu, 06/12/2014 - 22:57

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 also probably be using Confluence. I’m one of 3 writers, but 2 are based on Arizona, where the company’s parent company, Experian, is located.

If I’m (more)

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

Sun, 06/08/2014 - 11:09

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 writer” (more)

The future of tech comm is developer doc

Tue, 06/03/2014 - 12:23

I attended an STC presentation the other week by Andrew Davis (one of the most helpful recruiters in Silicon Valley) on Ageism and Today’s Technical Content Developer.

Ageism is simply bias against the capabilities of older people in the workplace, and it’s pretty rampant in Silicon Valley. Most programmers are twenty somethings who live on Red Bull and free company food, who roll into at work around 10am and leave at around 7pm in the evening, only to play v (more)

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

Fri, 05/30/2014 - 12:35

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. (N (more)

How to embed looping videos on your web page

Sun, 05/18/2014 - 18:24
.loopingVideo { border:5px solid #dedede; margin: 10px 0px; box-shadow: 10px 10px 5px #888888; }

Videos are great, but sometimes all you want to do is show a brief clip that demonstrates a certain action. For example, take a look at this article on how to make play-dough. Each step has an embedded, looping video that shows the action you need to take. There aren’t any player controls on the videos, and the videos only start when you mouse over them.

Embedding looping videos is easy to do with with HTML5 vi (more)

My Intercom article on gamification and user engagement

Sun, 05/18/2014 - 15:58

I was pleased to have my article, Gamification and user engagement in e-learning and documentation, included in the Bleeding Edge issue of the April 2014 STC Intercom magazine. Here’s a link to the article:

If you don’t have access to the Intercom, you can (more)

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

Sun, 05/18/2014 - 15:46

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:

What does DITA-structured help look like?

Thu, 05/15/2014 - 12:06

While documenting something yesterday, I ran across a help file that was unmistakably written in the DITA XML structure. Check out Jive’s help here. Jive is a community platform, kind of like SharePoint but more modern and clean looking. The webhelp output is published with Eclipse.

How can you tell when help is written using DITA? There are several giveaways.

Clear topic types. (more)

Complex tools versus simple tools

Sun, 05/11/2014 - 00:57

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 simple way to create and publish documentation u (more)

Upcoming webinar: Creating code samples for API/SDK documentation

Fri, 05/09/2014 - 11:42

I’m giving a webinar on May 29 on the topic of creating code samples. The webinar is sponsored by the soap conference, which is a new conference in Poland that I featured on my blog a few weeks ago. Here are the details of the webinar:

Creating code samples for API/SDK documentation

Date: May 29, 2014
Time: 8am PST
Cost: Free
Details: (more)