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 55 min ago

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)

Thirteen life hacks

Tue, 09/02/2014 - 00:51

The other day I ran across a post detailing 46 brilliant life hacks. Since then I’ve been mulling over a few of my own life hacks and wanted to share them here. The following are a few tips that have worked for me. They are totally random, covering “life” in general, but I’ll share them here in case someone finds them beneficial. (Sorry that I’m too lazy to be more unique with my images. Most of these images are from Flickr.)

1. To avoid c (more)

Thirteen life hacks

Tue, 09/02/2014 - 00:51

The other day I ran across a post detailing 46 brilliant life hacks. Since then I’ve been mulling over a few of my own life hacks and wanted to share them here. The following are a few tips that have worked for me. They are totally random, covering “life” in general, but I’ll share them here in case someone finds them beneficial. (Sorry that I’m too lazy to be more visual.)

1. To avoid carrying a bulky wallet in your pocket, get an iPhone c (more)

Author in DITA, publish with WordPress

Tue, 08/19/2014 - 10:23

If you’ve been following my posts lately, you’ve seen me explore the tools question numerous times. In this post, I’ll explore combining structured authoring with web publishing on WordPress.

In a nutshell, here’s the main idea: structured authoring tools are great for authoring content. Web platforms are great for publishing content. My plan is to leverage the best of both worlds by creating content using an XML editor like OxygenXML, and then publish it to a platform like WordPress.

Tech comm is great at authoring

Unquestionably, authoring content with a tool like O (more)

Author in DITA, publish with WordPress

Tue, 08/19/2014 - 10:23

If you’ve been following my posts lately, you’ve seen me explore the tools question numerous times. In this post, I’ll explore combining structured authoring with web publishing on WordPress.

In a nutshell, here’s the main idea: structured authoring tools are great for authoring content. Web platforms are great for publishing content. My plan is to leverage the best of both worlds by creating content using an XML editor like OxygenXML, and then publish it to a platform like WordPress.

Tech comm is great at authoring

Unquestionably, authoring content with a tool like O (more)

Woes of conditional text and topichead elements (DITA best practices)

Sun, 08/10/2014 - 16:01

When authoring in DITA, there are a couple of best (or worst) practices that I wasn’t aware of. The first is with conditional text; the second is with topichead elements:

Cautions with conditional text

Noz Urbina has written two excellent articles about the dangers of going overboard with conditional text.

Woes of conditional text and topichead elements (DITA best practices)

Sun, 08/10/2014 - 16:01

When authoring in DITA, there are a couple of best (or worst) practices that I wasn’t aware of. The first is with conditional text; the second is with topichead elements:

Cautions with conditional text

Noz Urbina has written two excellent articles about the dangers of going overboard with conditional text.

Benefits of tool diversity, part II

Thu, 08/07/2014 - 11:35

In my previous post, Is tool fragmentation a good thing?, I lamented the trend toward tool fragmentation in the tech comm community, noting several disadvantages that fragmentation brings:

  • fragmentation of community and knowledge sharing
  • increased overhead of learning new tools
  • frustration with HR departments who expect strong knowledge of their chosen tool (among hundreds)

I explored the appeal in having a standard method for tech comm that we can plu (more)

Benefits of tool diversity, part II

Thu, 08/07/2014 - 11:35

In my previous post, Is tool fragmentation a good thing?, I lamented the trend toward tool fragmentation in the tech comm community, noting several disadvantages that fragmentation brings:

  • fragmentation of community and knowledge sharing
  • increased overhead of learning new tools
  • frustration with HR departments who expect strong knowledge of their chosen tool (among hundreds)

I explored the appeal in having a standard method for tech comm that we can plu (more)

Is tool fragmentation in tech comm a good thing?

Tue, 08/05/2014 - 11:13

One of the attendees from Alan Houser‘s recent presentation at InfodevDEC meetup in Virginia the other night noted the following:

#techcomm trends/hypes, from @arh: There's no one technology that a majority of people are using. @infodevdc

— John Collins (@jrc_collins) (more)

Is tool fragmentation in tech comm a good thing?

Tue, 08/05/2014 - 11:13

One of the attendees from Alan Houser‘s recent presentation at InfodevDEC meetup in Virginia the other night noted the following:

#techcomm trends/hypes, from @arh: There's no one technology that a majority of people are using. @infodevdc

— John Collins (@jrc_collins) (more)

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)