Intercom Q&A: Sarah O’Keefe Answers Your Questions

Last week we put out a call for questions about Sarah O'Keefe’s article, “XML & Lone Writers: Can They Go Together,” in the December Intercom. You can read the article again at the Intercom site (don’t forget that you must be logged in to view the PDFs) before reading further for the questions and Sarah’s answers below. Come back next week and we’ll have another call for questions to an Intercom article for you! I’ve heard from other lone writers who say that they avoid XML because they think it makes them a little easier to replace. How do you counter that thinking? That question should have come with a beverage warning. In early 2009, nearly 30 percent of respondents in Scriptorium's structured authoring survey said they were working in XML. It seems to me that any writer who avoids XML is greatly restricting future job options. But let's address the larger issue. A writer's job security should be built on three items: writing ability, domain expertise, and tools. If these “other lone writers” are seriously concerned that XML will make them easier to replace, that suggests to me that they need to improve their knowledge about the products they write about. And I'm having trouble envisioning a scenario where learning FrameMaker or Flare is more of an obstacle than learning XML publishing. If your reason for existence as a lone technical writer is primarily your tools expertise, you are doing something seriously wrong. What are the first things I should try to explain to someone who doesn’t even know the first thing about XML when attempting to justify it? Try to relate it to something that they do understand. For example, in talking with engineers, I often explain that reusable content objects are quite similar to object-oriented code. For creative types, you might compare the move to an XML workflow as being similar to the industry shift from word processing to desktop publishing—it's a different approach to content publishing and requires a different set of skills. If you're talking to a management type, you should probably focus on process efficiency and all that money you're going to save with the new process, which will allow you to a) deliver more content, b) publish faster,  c) save money in localization, or d) all of the above. You state that there’s a discrepancy in the percentage of lone writers versus writers in larger groups who use structured authoring—20 percent versus 30 percent. Given the rest of your article, would you suspect that discrepancy is right about where it should be? Or do you think it should be a closer number? I'm not surprised at the discrepancy, and I think that the adoption rate accurately reflects the reality that the business case is generally less compelling for a lone writer than for a workgroup. That said, some lone writers do have strong businesses cases for XML but have not been able to convince their management. I'd guess that the disparity is something like seven percent “not compelling” and three percent “failure to communicate.” Can you play devil’s advocate for a moment and give some arguments a project manager might come up with in response to my forthcoming request? I think that would help to be able to quickly counter them. By the time you talk to management, you have presumably done your research and have a solid justification for XML. (By the way, “I think it's cool, and I want it on my resume,” does not count.) Here are some common objections and some possible responses:

• We don't have time for that. Actually, I'm proposing this because of our time constraints. In an XML-based workflow, we will save umpteen zillion hours [insert actual number based on your situation] because we eliminate all this manual formatting, rework, whatever. I'll be able to use the hours freed up there to accomplish Something This Manager Really Wants.
• It sounds risky. XML is an open standard, and we can use a variety of tools to create and edit XML files. Isn't that less risky than our current, proprietary tool? Also, I intend to create a prototype to verify that this works for our content before I commit. I think it's riskier not to move forward.
• It's too expensive. But look at my business case. We're already spending this money on [inefficient manual formatting, inefficient reuse, content duplication]. We'll recoup the initial investment in less than a year.

You give three choices if migrating content to XML: migrate everything, nothing, or selectively. Can you offer a few basic tips on which to do in what scenarios? The answer depends on how you intend to use your existing content in an XML workflow and how much your documentation changes from one release to another. For example, if you generally throw away old content and start fresh with a new release, or if your company doesn't update products but rather creates new products, it might make more sense to throw away old content and just start writing from scratch. Another case where you might not want to migrate is if you intend to rewrite content as part of the XML migration. It might be faster to write new content than to convert old content and then reorganize it. You might migrate all of your content in the case where content updates are incremental—perhaps 80 percent of your documentation is the same from release 2 to release 3? Since you can't predict which 20 percent will change, you migrate everything and then make updates. Selective migration makes sense if you know which pieces are stable and perhaps reused widely and which pieces are likely to change. You migrate the stable, reused bits and discard the bits that will change. So, for example, in a document that explains web browsing, reference information about HTTP protocol and HTML tags is probably stable. A section entitled “Current browsers” is probably going to have to be updated. Migrate the reference stuff; create a new section on browsers.