Shanghai Tech Writer

Single sourcing is a phrase thrown around quite often in the technical communications world. I’ve come across several posts that talked about it and even heard it mentioned a few times at work. Matter of fact, all the stuff I write at work are single sourced! But shame on me, I didn’t actually know what it was until just now when I looked up the definition on Wikipedia.

More about single sourcing another day when I am more coherent and articulate. After writing all day at work, the quality and quantity of my blog posts have degenerated to my dislike. At this rate, I’d never retire from the pennies earned from the content-generated ads. But that’s another post for another day. There are so many things I want to blog about but don’t have the time!

Back to single sourcing.

Today, I learned a cool new trick to documenting in XML. I heard about this trick before and was asked to implement it several times in my previous reviews. I kept putting it off because I didn’t know how and didn’t have the time to figure it out. But finally today, a colleague helped me figure it out!

This . . . it . . . is called the parent/child tag!

(Note: The use of this and it in technical writing is illegal but since I’m not working right now, I can write at liberty.)

Part of single sourcing is to simplify the process of reusing information/content that are reused several times across the same or different documentation.

For example, I’ve been working on a tutorial about designing digital filters. The first part of the tutorial is about designing floating-point filters. The second part is about designing fixed-point filters. The two filter designs are very different in nature, however, they share some of the same the procedural steps. So what do I do?

Attempt #1: The stupid way of documenting this is to write the instructions twice. Believe me when I say stupid. I actually did that and spent equal amount of time explaining the same things twice. Stupid egg. (笨蛋)

Attempt #2: The slightly smarter way of documenting this is to copy/paste the content that are reused. After I realized that some of the instructions in my tutorial are the same, I got smarter and started copying/pasting duplicate content. Only problem was that every time I got my review back and had to make changes, I had to make sure I fixed all the clones. Sometimes I forget and inconsistencies are just splattered across the tutorial. Bleh. Goose bumps.

Attempt #3: The smart way of documenting this is to use the parent/child tag (in XML)! I use the parent tag (<parent id=”id_name“>blah blah blah</parent>) to mark content that will be reused. Then wherever I want to reuse a particular content, I use the child tag (<child ref=”id_name“/>) to recall that particular content! It’s like magic! If I need to fix anything, I only have to fix the parent content! What a brilliant invention!

I’m starting to love the idea of single sourcing!

(No Ratings Yet)

 Loading ...

  Subscribe to RSS feed       Subscribe via e-mail