Kathryn Showers, Symitar, a Jack Henry Company

Members of our Implementations group came to us with a request: Will you please rewrite the Computer Operator’s Guide? What? Write technical documentation? That’s the job of the Technical Publications department… er… us, right. Sure, well, we would love to do it, except we don’t have any resources

[read: people] to migrate, review, test, and edit the materials. I wish we did, because the project is interesting, and an excellent poster project for showing off single-sourced, format-neutral, structured writing. If we wrote it well, we could replace a huge section in that pesky monolithic system documentation (that is our current deliverable) with concise, user-friendly DITA topics. If only I could see outside the confines of this resource box.

Serendipitously, the folks down in the Conversion Training department had a bit of down time between client site visits. We asked if they would be interested in helping out. Their response was a resounding “yes!” Not only were they quick, they were thorough and pleasant to work with. (My new best friends.)

The Implementations department manager identified a Subject Matter Expert (SME) who not only knew her stuff, but somehow took to granularity and re-use like… well, you know the cliché. She built a team to help her author, review, test, and assure the quality of the topics. (If you know me, you won’t be surprised that I’m inserting a “She rocks!” here.) We worked in sprints, collaborated often, and created a symbiotic process. Truly, our company is a “let’s-get-down-to-it, roll-up-your-shirt-sleeves-and-dig-in” kinda crowd. With that kind of willingness—combined with client-driven need and DITA know-how—we had to succeed!

Our Process

1. A Conversion Trainer, without any experience writing in XML or using DITA standards, migrated the information from Microsoft Word documents into an XML template.

2. The Implementations SME, also without experience writing in XML using DITA standards, revised documents for technical accuracy.

3. Our DITA writers tagged content, identified re-use, and copy-edited the topics.

4. I mapped, scrubbed, and initiated our tried-and-true collaboration process and served as the Project Manager.

5. Magic happened. No, really. Once our SME saw how we did the DITA thing, she “got” it. She began identifying big chunks of re-use and then telling me how to code it, structure, and map it. She was on fire!

6. The Technical Publications Software Engineer tweaked the toolkit, programmed style sheets and coded DITAval files, created tools to track percentage of re-use. You know, he pulled all kinds of tricks out of his hat, as magicians do.

7. Members of the Operations Support group reviewed our work and identified changes.

8. Our Editor meticulously edited our master re-use document and polished each topic.

9. The Technical Publications Software Engineer rendered the deliverables.

We repeated the steps above until we ran up against the deadline. It’s show time!

Test Driving the Deliverable

A member of the Implementations team took the newly minted Operator’s Guide to a client’s site, used it, and loved it. With a couple of technical changes to improve the accuracy, the guide will be perfect for the next road trip. However, there was one tiny problem: this Operator Guide focused on using VIOS hardware, and the next converting client purchased a different setup.

Our Implementations SME, along with her trusty sidekick, brought the Operator’s Guide to me decorated with sticky notes, flags, and highlighted passages. Truly, it was a thing of beauty. After examining the sacred text, it was clear that all we needed to do was modify and set an attribute to one step in the master re-use document and add a reusable sentence to several topics.

A couple of re-use changes, a couple of include and exclude lines in the DITAval file, minimal change to the cover sheet: 100% re-use. A single source and two deliverables (with a third in the works): is anyone besides me feeling the excitement? Did you catch the between the lines stuff? The part where we’re delivering custom, hardware-specific documentation to our converting clients?

But, did I ride off into the sunset and bask in the glory of success? Noooo! I have to get the notion into my head that this approach could be applied to other projects as well. For example, our Network and Hardware Services (NHS) department—the gifted engineers who install and configure the hardware at our clients sites—like to leave the client system administrators with a job aid. As it appeared to contain many of the same topics we already DITAsized, I planted my… er, self in the guest chair next to the desk of one of the NHS managers and opened my mouth. I swear, I sounded like a used-car salesperson. If you met me at a previous CIDM conference, you have already experienced the enthusiasm I have for Information Architecture in general, and XML-based structured writing a la DITA specifically. Just imagine my normal level of enthusiasm ratcheted up a notch or ten. With glittering eyes and bated breath, I’m positive I was the epitome of a DITA junkie waiting for her next fix.

And he said no.

But, this project was right up his colleague’s alley. We shook hands and scheduled a meeting to start the collaborative process yet again. I was positive we could parlay this into a customized, hardware-specific, conditionally processed documentation paradise. It was almost anti-climactic: “been there, done that, generated the deliverable.” What I needed to truly satiate my need for DITA bliss was a bigger challenge. How can I re-use the content that is in the Operator’s Guide, soon to be segued into the System Administrator’s Job Aid, into something more?

Meanwhile, both of these projects chipped big chunks out of our DITA migration project. Imagine, writing DITA deliverables for other departments that directly affect our migration in a very positive, very productive way. I wish there were another department that could benefit from the fruit of our labor. Wouldn’t it be awesome if we could get another group excited about single sourcing?

You know … we have talented Instructional Designers in the Education department who created and maintain the Computer Operations instructor-led class. The steps they use in the Computer Operator courseware are exactly the same as the steps we painstakingly detailed in the Operator’s Guide. Wouldn’t it be cool if we built around the reusable content already written and used it in deliverables for two separate departments? I pitched the idea to my supervisor, who let me run with it (albeit, with a short leash). I can’t wait to share what happens next! Be on the lookout for the next installment of this saga.

In a Nutshell

  • Thinking outside of the box (trite, but true)
  • Finding content authors outside of our department who simultaneously fill the needs of both their department and ours
  • Letting other departments feed the raw, unedited knowledge into the XML templates and letting the experienced XML writers DITAsize and code it
  • Collaborating up-front, and often
  • Working in sprints that trigger collaboration sessions
  • Taking it to the next level: searching for other deliverables and departments that can leverage the topics we painstakingly crafted

About the Author
Kathryn Showers
Symitar™, a Jack Henry Company

I am the Technical Publications Information Architect at Symitar, responsible for migrating core and peripheral product line documentation to DITA. Truthfully? It’s more like playing. I get to puzzle out how to theoretically break things apart, and then put them back together with structure and logic. Yes, I’m a geek, nerd… whatever.

I love this DITA stuff, so much I even write about it. Each new project gives me a bursting enthusiasm I simply cannot contain. I just gotta share. I contribute to the CIDM newsletter and I have presented at several CIDM annual conferences.

Some of my co-workers claim I’m a visionary. I’m flattered, but honestly, I’m just a teacher at heart. I bring my past experiences as a technical trainer, help desk supervisor, and technical writer to the job, using those experiences to create the foundation for user-friendly documentation.

I married my husband, a ballroom dance instructor, over 17 years ago, and we are blessed with two girls and a boy, all in elementary school. I love handmade items, and I’ve always had my hands busy with something crafty. My current crafting passions include scrapbooking and card making, with a bit of knitting thrown in just for the heck of it.