Tuesday, July 12, 2016

Number 4... A Million Times Number 4

Even without using DITA on a daily basis, item 4 on this list of The Ten Commandments of DITA/ applies to me.
4. Thou shalt not copy thy neighbor’s text.
Stone tablet version Thou shalt not copy they neighbor's text.
Texture: Patrick Hoesly (flickr)
DITA provides lots of options for reuse. Copying and pasting is not an acceptable choice when you have keyrefs, conrefs, topic-level reuse, and more. Reuse is good. Copying is bad.

The ability to reuse content and not to copy & paste it from one page to another is why I fell in love with Confluence and why I am ecstatic when I can set up a user-defined variable (UDV) in my RoboHelp project. For example, I am writing about 16 systems. Each system has a page with a table that has links to 5 sub-pages so that's 16 pages with a table that goes to 5 sub-pages that have the same name. For example:

Section Description
System A Recovery Procedures View how to perform procedures.
System A Server Information View information about the servers.
System A Data Flow View information about the flow of data through the system.
System A Backup Schedule View information about the backup schedule.
System A Contact Information View all contact information.

I created a UDV for each phrase after "System A" in the Section column. I created a UDV for each row in the Description column. Remember, there are 16 pages exactly like the table above. If I didn't use UDVs, and wanted to make a global change to this text, I would need to edit those 16 pages manually. If I were needing to change each row in the Description column, I would need to make 80 manual changes. Because I'm using UDVs, I make 5 changes (because I have 5 UDVs) and the same work is done much more efficiently. While I am unafraid of working hard, I am afraid I don't want to work stupidly.

No comments: