The DITA Olympiad
Approaching and Managing a DITA Migration Collaboratively
As the Information Architect (IA) for Symitar’s Technical Publications department, I have a vision—and a grand plan—for migrating our monolithic system documentation to DITA-structured XML. Only, I must communicate that plan to my boss and my teammates. Communication isn’t a problem. Boy, do I know how to talk. Getting control over this massive undertaking isn’t a problem, either. I don’t have control issues; I’m in control, this isn’t an issue.
What our department really needs is a development process that encapsulates my vision and depicts each step of the grand plan. It is time to research development processes.
There are lots of development processes out there: Agile, Agile with Scrum, Stage Gate, and so on. I wonder what other departments at Symitar use for their development processes. An epiphany happened during a chance tête-à-tête with a co-worker. She picked my brain about the internal process I went through when defining a writing project and immediately jumped on the fact that it parallels our Product Development department’s process to a “T.” Thus, the Technical Publications Development process was born.
Let the games begin.
Defines the extent and complexity of a project, as well as assigns specific roles to a person or group.
What does a Project Scope look like? Why start with that? Well, you have to start somewhere, and this seems as good a place as any… Now where is that template…?
I invite writers, subject matter experts (SMEs), and other interested parties to an initial meeting to understand the extent of a potential project. This meeting is a combination of a fact-finding mission and an exercise in defining the attendees’ wish list items.
Once I’ve picked apart all the ideas and sifted through the facts and wishes discovered in that meeting, the pieces, as they relate to tagging and coding, begin to take shape in my mind and I start writing; not the scope, mind you, but a prototype. I take seriously the adage, “You can’t really understand another person’s experience until you’ve walked a mile in his shoes.” I can’t explain how to write, tag, map, or add metadata to the tasks, concepts, references, or any other topic until I’ve explored it myself. After I’ve played (defined as: exercise or activity for amusement or recreation) in my DITA sandbox for a while, I tackle writing the Scope and begin a Technical Design. (It is much easier to develop both simultaneously.) Now that I have finished playing and have written the Project Scope, assembled a prototype, and started the Technical Design (defining what the heck I did, and why I did it that way), it is time for another meeting of the minds.
The Scope Meeting is a chance to reflect back to the group “is this what you mean?” It is an opportunity to define what the project is, or is not (successfully preventing scope creep). It is the group’s opportunity to clarify, refine, and approve the Project Scope. When the Scope meets the group’s vision of “what it looks like when it’s right,” then I present the prototype I’ve secretly constructed. (This is the “Ooooh” and “Ahhh” part.)
Now that the group can see what we are talking about, they generally have more questions, like these:
- Can we do…?
- Will we be able to…?
- How come…?
- Why isn’t…?
Nine out of ten times, I’ve anticipated and addressed those questions in the Scope. Whew! When I don’t anticipate a question, we tweak the Scope until we all agree. (Patience, Grasshopper. It’s worth it! Besides, once you’ve done a few Scope meetings they go fairly quickly.)
Forgive me for being trite; but, now that we’re all on the same page, let’s move on.
Guidelines and examples of how to write and tag the project based on the prototype developed during the Project Scope.
It’s a living document, and as the project progresses we add, change, and clarify the Technical Design. It contains examples of how to present, code, and save each topic (see Figure 1). DITA collides with Minimalism here.
A nod to granularity: Our Technical Designs are in themselves granular. Our writing projects are evolving, becoming more and more complex. For example, when writing a Technical Design for a project that has several new fields and privileges, we link to already-defined Technical Designs for those portions of the project.
From a writer’s point of view, this is where the action takes place. This is where the artistry of writing comes alive. This is where dull, lifeless, repetitive pages are transformed into meaningful, vivid, and concise prose. Ah, the beauty of it!
From a manager’s point of view, the Technical Design becomes a training document for new hires or for other writers joining the project at a later date. It documents the history of decisions and the bases on which they were made. It’s the authority on policies, procedures, and established workflow.
From my perspective, it’s a life saver because I don’t have to hold everything in my head or try to remember every nuance or discussion thread while under the pressure of production. It’s also a time saver because my teammates are at liberty to review the Technical Designs anytime rather than coming to me for answers to questions. Does that rock, or what?
Planning, organizing, and managing resources to bring about the successful completion of technical writing projects.
Have you ever experienced that feeling that combines immense satisfaction with soaring elation and occurs when everyone involved in the project is excited about the go-forward plan and eager to get started? Are you equally familiar with that piercing stab once you return to your desk? You know, the “What the heck did I just get myself into” feeling?
You know your boss is going to ask questions like, “How long is it going to take? How will the project impact, or be impacted by, our current deliverables? What is the priority? Will an industry standard of 10 pages per day constitute a good baseline for estimating delivery dates? How many projects can one 10-person department manage before sacrificing quality, missing deadlines, or scrapping the whole DITA idea?”
If you just made it through that paragraph and now feel tremendous anxiety, welcome to my world. Scrapping our DITA isn’t an option. Sacrificing quality or missing deadlines? Hello!Type A personality here! That’s just not going to happen.
I needed to define what I wanted in a tool that didn’t just track the number and type of XML topics. I also wanted to know who wrote the topics and where the topics were in our production cycle. I created a simple Excel spreadsheet (see Figures 2 and 3) with nifty drop-down menus to reduce repetitive entries. Come to find out, it was a great way to match up the topics written with the topics mapped. For lack of an inspired name, I dubbed it MapMinder. I thought that maybe I could add a few simple calculations: the total number of topics, how many were written, how many remained, and so on. Since I went to that extent, I also added calculations to determine how many topics were mapped, had been edited, needed re-work, or were completed.
Next, I set up links to access the Scope, Technical Design, and MapMinder for each project. I wanted to see at a glance our priorities, the lead writer for each project, and our target dates, including the number of days we were ahead or behind on each project. I also wanted my manager to be able to get to this information quickly, so I shamelessly plagiarized the current buzz word for management tools and created my own Project Dashboard as shown in Figure 4.
Correcting, revising, or adapting written, DITA-structured XML documents for publication or presentation.
Remember: We have multiple ongoing projects, so our editor, QA analyst, IA, and manager must try to keep the conventions for each project straight in their heads. (Forget that! Theycan keep stuff straight in their heads. I’ll read the Technical Design.)
Together the manager, editor, writer(s), QA analyst, and I have already gone through several iterations of collaborative writing. Our process states that once the writers complete a document, they update the status in the MapMinder to Map. Then I (the IA) peek through the content to correct or question and lightly edit. I might even write a concept or two. Once I’m satisfied that the package is complete, I forward to the editor a link to the map so she can enjoy a bird’s-eye view of the whole kit-and-caboodle. Because we’re no longer talking about misplaced commas, verb agreement, or activating passive voice, it’s necessary to deliver the project to our editor as our clients will receive it (in context, as shown in Figure 5).
Our editor starts her process with the common phrases document (a reusable file). Once she’s satisfied with the content’s phrasing, grammar, and tagging, she moves on to edit the topic, task, and reference documents. (This is the exciting part; I know, I’m a geek.) The tasks contain up to 80 percent conrefs, which were already edited in the common phrase documents! Sweet.) Layer by layer, she looks for holes in the content, identifies missed possibilities for reusable content, questions maverick tag choices, and removes empty tags.
Now we have reached the final stretch.
The Finish Line
Documentation is delivered to clients with XML files seamlessly integrated into our eDocs.
We talked about it. We (the writers, the ones who actually did the work, bless them) wrote about it. We mapped it. We edited it (and when I say “we,” I mean our goddess of an editor).
Did we do it? Did we succeed? Did we get the gold medal? Let me share the testimonials with you in Table 1.
The Tech Pubs team wins the Gold Medal!
The crowd goes wild, mayhem ensues. Yup, it’s just another day in DITA paradise.
Because we took the time to perform a post-mortem analysis on the process, we are pleased to announce two new DITA Olympic teams participating in the fall DITA Olympiad: the Integration into eDocs and Quality Assurance teams.
About the Author
Symitar Sytems, a Jack Henry Company
Kathryn Showers is the Information Architect for Symitar, responsible for migrating core and peripheral product line documentation to DITA. She has a flair for enticing information from reluctant sources and into the hands of those who need it, mated with a knack for reducing highly complex concepts to easily understood elements. A mother of three children under 10 and married to her wonderful husband for 17 years, Kathryn spends her “down” time enjoying her beautiful family and scrapbooking.