← Reduce, Reuse, Recycle: Developing a Reuse Strategy for DITA

What are you doing with DITA? →

Posted on January 30, 2011 by Karen Lowe

I’m lazy.

And because I’m lazy, I tried to reduce the time I spend doing something, especially something that I find monotonous. Like chunks of standard markup, for example, to create a screen guide or reference topic. Adding the tags and labels are not very thought provoking. Necessary, but I’d rather be walking on the beach!

So to reduce this time, I found a way to “automate” the job. The end result is a marked-up DITA content.

OK, it’s not actually automation; it’s just using a spreadsheet application (Excel or OpenOffice Calc) to do the leg work. (If you have developer skills, you probably could automate this whole process).

By using formulas in a spreadsheet, you can add the required tags. All you have to do is enter the field names/labels as they appear in the application and copy out the ‘finished’ version straight into the XML. As a result, the topic has the framework and tags. It’s ready for the meat of the content and I have more more time to prepare this more valuable content.

I’ve used this technique to create table entries, conrefs for reusable field names as well as DITAmaps and entire topics.

For Table Entries

Put your field label in column A, starting at cell A2.

In B1, write out how you want the final code to appear. For example, <entry>Field Label Here</entry>.  Then replace the Field Label Here with XXXs. Doing this gives you a standard size of text to replace. So you’re example would be <entry>XXX<entry>. Those XXXs will be changed–replaced by another cell. You’ll need to count over the number of character to the XXXs (in this case, it starts at the 8^th character and goes for 3 characters).

In B2, insert a formula to replace character 8 and the next 3 with text from a different cell. For Excel, it’s =REPLACE($B$1,8,3,A2).

TIP: If you’re using OpenOffice Calc, try semi-colons instead of commas in the formulas.

Copy the formula in B2 down and you’re ready to type in the field names. As you do, the text in column B will be ready to insert into your DITA table in your XML editor. My XML editor removes any extraneous tags put in by Microsoft, but if yours doesn’t, copy it to Notepad first and then into the XML editor.

Another tip: Simon Bate from Scriptorium has posted a Quick Word to DITA table conversion blog entry that covers how to get a full table into XML with relatively little effort.

What if There Are Attributes (Quotes)?

In some instances, the quotes around attributes get problematic. Here’s how I’ve dealt with that issue:

Type out the entire DITA code in one cell, including the attribute and its quotes. For example, <entry><uicontrol outputclass=”field”>Field Label</uicontrol></entry>. Replace the Field Label with the XXXs again, and count over to the location of the XXXs. Don’t forget to include the space in your count. For this example, it’s <entry><uicontrol outputclass=”field”>XXX</uicontrol></entry>. The XXXs are at 39, so the formula is =REPLACE($A$1,39,3,B2).

If you want, you can add the <row> tags to create the entire content of the table.

Creating the CONREF Content

Our reuse strategy states that screen labels should be in one reusable topic and whenever content refers to that item, use a conref. To add in a bunch of new fields with the development of a new screen, I used Excel to create the reusable items quickly.

Start with what is needed: <ph id=”field_name”><uicontrol outputclass=”field”>Field Name</uicontrol></ph>. Note the changed capitalization and the lack of spaces in the id. That’s what makes this one a four-formula, six-step process:

1. Start by typing the Field Name in column A, starting at the second row down. The first one is in A2.
2. In the next column, convert the Field Name to all lower case using the formula =LOWER(A2). This puts the lower-case content in B2.
3. In column C, replaced the space with an underscore using =SUBSTITUTE(B2,” “,”_”) (NOTE: Calc, it’s =SUBSTITUTE(B2; ” “; “_”). This gives you the phrase’s id in cell C2 for use in the next step.
4. Split out the parts you want into cells B1 and C1. For example, the fragment <ph id=”XXX is in cell B1 and the rest of the fragment “><uicontrol outputclass=”field”>Field Name</uicontrol></ph> is in cell C1. Again, replace Field Name with YYY, again so you have a standard 3-character item to replace. It now appears as “><uicontrol outputclass=”field”>YYY</uicontrol></ph>.
5. Add the replacement formula. Use =REPLACE($B$1,9,3,D2) in cell E2. Use =REPLACE($C$1,34,3,A2) in cell F2.
6. Pull everything together with the Concatenate formula =CONCATENATE(D2,E2) in G2.

With  this created, you just enter the field names into column A and copy column G2 to your XML editor.

You can reduce the number of columns by stringing some of these formulas together, like =CONCATENATE(REPLACE($B$1,9,3,D2),REPLACE($C$1,34,3,A2)).

Further Ways to Leverage Spreadsheets

Once I got the hang of Excel’s formulas, I created a few more formulas in other columns to set up the conref itself. With all of this done, I can copy out the reuseable piece into the reusable topic and the conref part into the specific topic. Another advantage of Excel is that the columns can be sorted, so I can see if I have unnecessary duplicates.

Another way to leverage this is to use a spreadsheet to create a stub topic. Using the REPLACE and CONCATENATE formulas, I created the header lines, the topic framework and some generic content (a CONREF to our “under construction” phrase). I can then copy out only one column to create valid content to populate an XML file.

After commenting to a developer friend about how clever I was, I quickly learned that I was just a novice. He commented that it’s easy to create a script to pull the filename from one column, insert another column as the text and save the file to a folder. (I don’t understand the scripting language but, if you do, more power to you.) With my spreadsheet and this script, the topics that used to take me all day to create could be available in about 5 minutes. That left me the rest of the day to find the content to make these topics meaningful. (Although I would rather walk on the beach…)

What’s Your Mileage Like?

I believe that because DITA is standardized, this technique works well to get content into the XML code. Does this work in other tools?

Have you got something other labour-saving tip to share? Did this help you? Drop me a line to let me know.

This entry was posted in Reuse, Writing. Bookmark the permalink.

← Reduce, Reuse, Recycle: Developing a Reuse Strategy for DITA

What are you doing with DITA? →

Leave a Reply Cancel reply