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

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)

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)

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)

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)

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)

The part of the brain you should listen to when writing

Wed, 07/16/2014 - 11: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)

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)

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)