DITA Chicks Blog

Dental surgery is no fun. And it’s hard – hard to learn for a practitioner, hard to be in the dentist’s office, hard to bear it as the patient.

But this hard thing is necessary.

Imagine (or remember) an ache in your jaw. A nagging, dull sort of ache. You ignore it for a while, live with it, tolerate it and work around it. Until one morning, the pain seems to stand up. It shoots something into your brain and demands attention. Your nerve-endings are working overtime telling you that all is not right in the state of your mouth.

So you admit to yourself that you need help. You bite the figurative bullet and go to the dentist.

Necessity

It sucks while you’re lying on the chair, your mouth wide open, listening to the drill, smelling things that you’d rather not. But you endure it.

Why? Because after it all, it’s worth it. When the freezing wears off and the memories fade, the original pain is gone. Usually, your mouth is in a better state, there’s no pain when you chew, no discomfort in the middle of the night.

You can get on with your life.

Dental Pain at Work

Your content is increasing. Your clients access your information on their iPad, their Kindle, their mobile phone as well as in PDF and regular web form from a desktop. They want to access your content in the language that they speak. They’re distracted and frustrated. They want something that will help them now. If what they find is inconsistent, they’ll question it, doubt it or, worse, abandon you.

Your company wants to send out targeted product messages, but messages that are consistent and suitable for different devices. Your company wants to reach a bigger audience while keeping the translation costs in check. It wants to reduce support costs but keep satisfied, happy clients. Your company wants to make the right information easier to find – for the clients and for the employees.

You need to reuse the same information in multiple outputs. You want to be able to update it quickly, and have the changes cascade to each output. You need to spend your time on the content. You need to stop cutting and pasting. You need to stop spending a day fixing the format of each output.

You need to have a better strategy to cope with the evolution of information. You need to separate content from format. You need to move your content to something that will help you cope with the present and meet the future.

Suck it up, buttercup.

Do the work necessary to make things better. Look into XML and DITA. Be strong – don’t shy awaybecause XML is different, DITA is not WYSIWYG. Like dental surgery, short term pain (the learning curve, the paradigm shift) can result in long term gain.

As a writer, being a technical writer sucks. Really, think about it. We spend all our time writing stuff nobody wants to read. Nobody! I write this stuff and even I don’t want to read it.

Meet your Typical User

I recently bought an iPad. There is an online user guide. I haven’t really used it much. For the most part, I love this gizmo, but there is one thing about it that annoys me to no end. It’s the auto-correction feature. I don’t have a problem with the idea of it; I think it’s great. But ignoring a suggestion wasn’t intuitive, at least not to me. I tried a number of different things, but none of them were working. In exasperation, I went to the user guide. I was frustrated and a little ticked off at this point. I wanted answers! I didn’t want to know how to shut the feature off entirely, just dismiss individual suggestions when they weren’t appropriate for me. How do I do that? That’s it. That’s all I wanted to know. Nothing more, nothing less.

I am a typical user. This is how the majority of our users land on our help sites. Frustrated, annoyed, looking for answers. They are trying to do something and it’s not working. They’re often working towards a deadline, or trying to finish a task so they can get to the next thing on their long to-do list, or get out the door to meet someone for lunch or pick up their kids. They are not interested in reading a beautifully crafted work of art, or wading through jargon and market-speak. They don’t care about the finer points of grammar, so long as they can understand what you’re saying the first time they read it. They just want an answer to their question.

I eventually found my answer, but I didn’t find it in the user guide. I Googled it. I don’t recall the site I found it on, but it wasn’t an Apple site. Apparently, I wasn’t the only one that didn’t find it intuitive.

How DITA Can Help

DITA is geared to help us help our users by its very design. The topic approach breaks content down into bite sized chunks, and each topic is meant to answer a single question. Just one. No more, no less.

Related links can point them to additional information if they really want it. But if your topic answered their question, chances are they’ve moved on! If your topic didn’t answer their question, the related links can be an opportunity to redeem yourself.

Answer the Question

Although DITA is designed for writing answers to a single question, it doesn’t happen auto-magically. Ultimately, the writer determines what goes in the topic, and no amount of structure can force you to stick to the topic at hand. But if you really want your technical writing to be appreciated, do yourself – and your users – a favor. Answer the question. Even the ‘obvious’ ones.

If the earth had a yearbook, I’d like to see the one from 1000 years ago and compare it with this year’s.

Yearbook (Peter Galvin / Flickr.com / Creative Commons)

The dodo would be missing. And DITA chicks would be a new species.

The pages showing the environment would look drastically different. And the page for the work environments would be different in this year’s book compared to that of only a few years ago. The business environment is changing, evolving and growing in complexity.

In this world of diversity and change, how can we cope?

The Only Constant Is Change

Philosophers tell us that change is the only thing that we can count on (ignoring of course, death and taxes). Heraclitus noted that ‘nothing endures but change’ and Isaac Asimov added that we must “take into account not only the world as it is, but the world as it will be.” Continue reading →

Wild and Wonderful

I’ve never thought of DITA as an output format. I read this post  by Julio Vazquez nodding in agreement, but the comments were enlightening. They got me thinking and wondering about all the wild and wonderful things that people are doing with DITA.

There are a number of cool DITA projects that have been chatted up in blogs and tweets, many of which have, or will be contributed back to the community. For example:

• DITA4Publishers: A community project to enable the quick and productive use of DITA by Publishers, including plugins for generating EPUB and Kindle electronic books.
• DITA4All: Extending the range of application of DITA is a major goal of dita4all. They are developing techniques for creating websites based on DITA source files.
• DITA to Drupal:  Building a DITA documentation distribution module for Drupal.
• DITA to WordPress: Developed a WordPress import mod­ule which will take the two-pane ‘Web Help’ out­put from the DITA Open Toolkit and import the hier­archy of XHTML pages into WordPress.

But what about the less publicized projects? What cool things are people doing with DITA, whether strictly using the Open Toolkit, or developing their own scripts or tools to solve every day business problems?

In her last post, Karen wrote about using Excel or OpenOffice Calc to create DITA markup. Other cool things we’ve done include:

• Combined our product content with our client’s content to produce a custom content solution. We initially used DITA’s chunking feature, and our java developers created a script to dynamically generate the custom map, using file naming conventions to find matching topics. This allowed our clients to add their content to whatever topics they wanted and eliminated the need to manually manage their additions.
• Generated HTML content that is then pulled into a Sharepoint site via a web part.

I’ve heard a lot of people ask about transforms for DITA to a slide show presentation. Last summer on an Advanced DITA course, I met Ben Colburn from Citrix. They took a different approach to the problem. Rather than create an XSLT transform to push content to a slide format, they developed some VB scripting to pull DITA content into Power Point. And they’ve contributed their code back to the community.  (You can also check out a recent presentation Ben did with Joan Laselle of Laselle Ramsay on creating a business case for DITA.)

So, what cool and fun things you are doing with DITA? We’d love to hear about them and I’m sure our readers would too.

I’m lazy.

Walking the Beach

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.

Reduce, Reuse, Recycle Flickr:Tara Chill

How do you develop a reuse strategy for DITA? A very good question. While there is no one-size-fits-all strategy, you can  take a systematic approach to get there. Our approach has been one of Reduce, Reuse and Recycle.

Being an agile project, our journey has been iterative, and with our recent upgrade to the DITA 1.2 spec, our strategy continues to evolve. We’re living proof that you don’t have to do it all at once. You can start small, and build on it. However, I believe an initial understanding of the process and the DITA features available will help you in the long run.

Continue reading →

We’ve all been doing Christmas for a while now. Even if you’ve only had 20 or so, I’m sure you’ve got things that you do this time of year that shape your holiday. We slide into our family events, be they religious or not, and these traditions grow in importance as we grow into adults. They help this wintery time of year feel special.

Being the TV-addicted generation that we are, Christmas specials, like Rudolf the Red Nosed Reindeer, Frosty the Snowman and How the Grinch Stole Christmas, have always marked the arrival of the holidays. They start the anticipation and remind us what’s important in this season.

Every member of any family has expectations around the holidays. Satisfying these make traditions more solid. Not unlike topic-based writing.

How so, you say? Well, humour me as you think of these connections:

Traditions

Traditions lead to expectations – and predictability.

In my family, there’d be trouble if I didn’t make the Christmas morning Cinnamon Sticky Buns from scratch. It’s a tradition that grew out of my own childhood (Thanks, Mom!) and it’s intricately tied to other traditions. The Christmas atmosphere is enhanced by the yeasty smell of them rising on Christmas Eve, while we argue over whether or not to open one – just one – present early. And the aroma filling the house the next morning while they bake and we open presents is definitely a huge part of our Christmas morning structure.

As a writer, there are certain things I do when I prepare to write, write and then review.  My personal “traditions” put me in the right frame of mind to compose the words on the page and then to trim those words down to only the needed ones and put into the topics where they’re needed.

Giving

My kids expect to get presents on Christmas morning. Heck, I expect to receive something on Christmas morning!  So we all prepare for that. We go out to gather them, then sort through them and finally put them in the right gift wrapping for the receiver.

As writers, we do that for the reader. We gather the information, sort it into small enough packages and wrap it up for the reader. (DITA sure helps with this.) When a reader opens up my help file, they expect to receive knowledge.

In both settings, I try my best to deliver the goods.

Structure

Christmas traditions frame the holiday structure. Things we do before the actual special day, things we do on the day and things we do after the day are all important pieces of the whole season.

I try to include that structural approach when I create help files. I gather the information, organize it, compile it in its wrapper and deliver it on the day it’s expected. Topic-based writing relies on structure to help give it meaning. When I write the task up for the reader, I think about the things you need before you do the task, things you do to get the job done, and finally next steps so you can move on.

Similar structure, right?

Evolution of Structure – Access

Years ago, my family and I would scour through the TV guide to figure out when those Christmas specials came on. Then we would arrange our schedule around them. Now, however, we have those specials on DVD so we can watch them whenever it fits our schedule.

Information access used to be dictated by the owner of the information. For example, the company told you when the support people would answer your questions. But now, the expectation is that the information is out there in topics on the website, waiting for you to look. Information on demand (and the delivery vehicles that make that possible) fit the reader’s schedule. XML and automation make this possible.

Evolution towards Quality

Years ago, my kids were happy with plastic toys that made noise. (Actually, the wrapping paper and the box would entertain them for hours!) Now they’re much more sophisticated in their taste and their interests. It’s quality they look for, not quantity.

Ditto with the information you deliver. Readers’ information needs have matured and evolved, just like my kids. Readers don’t care about the number of pages you can pump out in a day; they care if the information you provide helps them with their issue, whether that’s troubleshooting or learning about a product feature.

Be good, be succinct and be useful.

And the Message

Rudolf wanted to be important in his own way, to do his job and show Santa that he could really shine at it (sorry – but you know I can’t leave those word-opportunities alone!) and by the end of the show he overcomes hardships on his path to success, glory and happiness.

Frosty wants to spread his cheer to all and help every one of us be treated as the special individuals we are.

Even the Grinch learns the true meaning of Christmas by the end of the show and he, the Grinch himself, carves the roast beast.

As writers, we too want to succeed at our jobs, we want to spread good-will about our subject and we want the reader, every reader, to get the message. I don’t know about you, but I try to keep this hope alive throughout the year, even through the hardships of difficult SMEs or the storms of uncertainty.  As this year comes to a close, I hope that you too find the strength to keep at it, keep writing and keep looking for the fun while you’re at it.

Let the learning, the special-ness and the duties of this season be fulfilled and fulfilling to you.

Happy Holidays!