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: 2 hours 42 min ago

Simplifying DITA authoring by using a Markdown to HTML to DITA workflow

Thu, 10/30/2014 - 02:28

The other day I started to organize my notes on Java, and knowing that I eventually plan to publish these notes, I wondered what format I should write the content in. My first thought was, hey, I wrote my DITA QRG in DITA, so why not store my Java notes in DITA as well?

And then I had this nasty feeling of dread where something in my chest cringes and shrivels. If I was going to be drafting this content, the last thing I wanted to worry about was XML markup tags and structural complexity.

Were I to draft the content in DITA, I (more)

Slides and recording for “Perfecting the audio narration in instructional video” at Info Dev World

Fri, 10/24/2014 - 01:35

Today at Information Development World I presented “Perfecting the audio narration in instructional video.” Here are my slides and recording.

Perfecting the audio narration in instructional video from Tom Johnson

PowerPoint in other format: (more)

Upcoming presentation at #InfoDevWorld: Perfecting the Audio Narration in Instructional Videos

Wed, 10/22/2014 - 02:10

I’m giving a presentation this week at Information Development World on voiceover with video tutorials. My presentation is Thursday at 2pm. Here’s the description:

Perfecting the Audio Narration with Instructional Videos

No matter what tool you use to create video tutorials, getting the voice right — sounding professional, clear, and friendly — is an art. You have to know to interact with your microphone, how to read your script sounding natural and at ease (often while driving the mouse), how to post-process your (more)

DocOps: Interview with Jim Turcotte

Tue, 10/21/2014 - 11:32

Jim Turcotte

The following is an interview with Jim Turcotte, a senior vice president for CA Technologies and business unit executive for the Information Services team. Jim recently posted several articles on LinkedIn Pulse about something he calls DocOps, so I asked him some follow-up questions.

Can you explain DocOps in more detail?

First, let me start by explaining the application economy. Customers today decide whether or not to do business with you based on your software. Your new façade is now your mobile application and online presence. A (more)

API Doc presentation slides and recording

Thu, 10/16/2014 - 09:56

Yesterday I presented “Publishing strategies for API documentation” to the San Francisco STC chapter. Here are my slides and recording.

Publishing strategies for API documentation from Tom Johnson

PowerPoint in other format: (more)

Import DITA XHTML Output into WordPress

Tue, 10/14/2014 - 20:53

I’ve been working on some updates to the WordPress DITA Import tool. This tool allows you to import the DITA XHTML output into WordPress. For the full instructions, see this page on my demo site: Import DITA’s XHTML Output into WordPress.

I’ve mentioned this tool before on my blog, but I’ve made some updates to the tool:

  • Created a way to include the TOC navigation from the XHTML import automatically.
  • Changed the installation method so that updates to (more)

Outside the tech comm tool bubble, there is a wide, wide world

Thu, 10/09/2014 - 15:42

If you hang out in tech comm circles, attend STC meetings and technical writing conferences, and interact on tech writer blogs and forums, you might think the general tool options for professional technical writing goes something like this: You can use a help authoring tool, such as Madcap Flare, Framemaker, or Author-it. You can also structure your content in DITA, using an editor such as OxygenXML. If you’re a big corporation, you maybe publish your content on a CMS of some kind, like SDL or Ixiasoft. If you’re in a highly collaborative environment, you might use a wiki such as Conflu (more)

Why developers will never adopt DITA

Tue, 09/30/2014 - 21:40

Ever wonder why developers resist DITA so much? Take a look at this comparison. Here are two ways to describe a simple task of printing a page.

DITA syntax <task id="task_mhs_zjk_pp"> <title>Printing a page</title> <taskbody> <steps> <stepsection>To print a page:</stepsection> <step> <cmd>Go to <menucascade> <uicontrol>File</uicontrol><uicontrol>Print</uicontrol> </menucascade></cmd> </step> <step> <cmd>Click th (more)

Two major Confluence problems: poor content re-use and lack of wiki markup

Thu, 09/25/2014 - 01:16

The other day I tweeted about a brief frustration with Confluence:

I don’t mean to be critical, but I really hate using Confluence for doc. Am so happy to be migrating Confluence content to DITA. #techcomm

— Tom Johnson (@tomjohnson) September 22, 2014

And a couple of people asked me for a post with more detail.

@tomjohnson Please blog it. I’d really like some detail on this (more)

Using collapsible sections to bring tasks and concepts together (DITA)

Mon, 09/22/2014 - 11:24

Last week I showed how to integrate a sliding side panel into OxygenXML’s webhelp output. In this post, I show you how to integrate collapsible show/hide sections. As before, I’m using DITA as the structured content, which adds another element of complexity to the setup.

Demo

For a demo of the show/hide functionality, see Show/Hide Demo.

(more)

Foreword to Developing User Assistance for Mobile Apps, 2nd Edition

Fri, 09/19/2014 - 15:34

Developing User Assistance for Mobile Apps, 2nd Edition, by Joe Welinske

Joe Welinske just published his second edition of Developing Mobile User Assistance.

Although it’s the second edition, 300 of the 400 pages are new, making it mostly a new book. If you’re doing an (more)

Adding code comments through a sliding jQuery Sidr panel (DITA)

Tue, 09/16/2014 - 17:56

If you write developer documentation, you know that developers prefer code samples to narrative instruction. The beauty of code samples is that they provide context at a glance. You can see where variables should be declared, functions called, objects initialized, and so forth — all by just looking at the code. Trying to describe the same content narratively just doesn’t connect with users.

The problem is, you can only pepper the code with brief 1-2 line comments as instruction to users. These short signposts might be fine for advanced users, but for those times when you need mor (more)

STC Intercom Issue Entirely Dedicated to API Documentation

Wed, 09/10/2014 - 13:13

The September issue of the STC Intercom is entirely dedicated to API documentation. I had the opportunity to act as guest editor for this issue. As guest editor, I helped select the topics, find the writers, and did some editing on the articles. I also wrote a foreword to the articles. It was a pretty cool experience altogether.

This issue of the STC Intercom is entirely dedicated to API d (more)

STC Intercom Issue Entirely Dedicated to API Documentation

Wed, 09/10/2014 - 13:13

The September issue of the STC Intercom is entirely dedicated to API documentation. I had the opportunity to act as guest editor for this issue. As guest editor, I helped select the topics, find the writers, and did some editing on the articles. I also wrote a foreword to the articles. It was a pretty cool experience altogether.

This issue of the STC Intercom is entirely dedicated to API d (more)

Using WordPress natively for single source publishing and conditional content

Mon, 09/08/2014 - 03:37

In this series, I’m exploring ways to author in DITA and publish with WordPress. In previous posts, some commenters wondered whether it would be possible to simply author everything in WordPress, rather than continually importing from DITA. In this post, I’ll explore that model.

One of the strengths of authoring content directly in WordPress is quick turnaround (or velocity). When someone asks you to make a small update to your help content, such as adding a little note on one page, does (more)

Using WordPress natively for single source publishing and conditional content

Mon, 09/08/2014 - 03:37

In this series, I’m exploring ways to author in DITA and publish with WordPress. In previous posts, some commenters wondered whether it would be possible to simply author everything in WordPress, rather than continually importing from DITA. In this post, I’ll explore that model.

One of the strengths of authoring content directly in WordPress is quick turnaround (or velocity). When someone asks you to make a small update to your help content, such as adding a little note on one page, does (more)

Upcoming presentation in downtown San Francisco: Publishing strategies for API documentation

Wed, 09/03/2014 - 02:10

I’m giving the following presentation to the San Francisco STC Chapter on October 15:

Publishing strategies for API documentation

Most of the common tools for publishing help material fall short when it comes to API documentation. Much API documentation (such as for Java, C++, or .NET APIs) is generated from comments in the source code. Their outputs don’t usually integrate with other help material, such as programming tutorials or scenario-based code samples.

REST APIs are a breed of their own, with almost no standard tools for generating documentation from the sour (more)

Upcoming presentation in downtown San Francisco: Publishing strategies for API documentation

Wed, 09/03/2014 - 02:10

I’m giving the following presentation to the San Francisco STC Chapter on October 15:

Publishing strategies for API documentation

Most of the common tools for publishing help material fall short when it comes to API documentation. Much API documentation (such as for Java, C++, or .NET APIs) is generated from comments in the source code. Their outputs don’t usually integrate with other help material, such as programming tutorials or scenario-based code samples.

REST APIs are a breed of their own, with almost no standard tools for generating documentation from the sour (more)

Challenges in using WordPress for publishing DITA content

Tue, 09/02/2014 - 22:53

The other week I wrote a post called Author in DITA, publish on WordPress. Although the workflow from DITA to WordPress is possible and might work fine for many situations, there are significant challenges in using WordPress as a publishing platform.

Authentication

One major reason why WordPress is difficult to adopt as a delivery platform for help content is authentication. If your help is openly accessible to everyone on the web, then authentication doesn’t pose a problem. But if you only want p (more)

Challenges in using WordPress for publishing help content

Tue, 09/02/2014 - 22:53

The other week I wrote a post called Author in DITA, publish on WordPress. Although the workflow from DITA to WordPress is possible and might work fine for many situations, there are significant challenges in using WordPress as a publishing platform.

Authentication

One major reason why WordPress is difficult to adopt as a delivery platform for help content is authentication. If your help is openly accessible to everyone on the web, then authentication doesn’t pose a problem. But if you only want p (more)