You don’t have to bet the farm…
A wise man once told me that the goal of marketing is to frame the question so that what you are selling is the best possible answer. In the world of tech comm publishing, the default question has been: “What tool should I use?”
That is the wrong question. When you start by asking about tools, you immediately go down the rabbit hole of software usability, vendor longevity, and operating system support.
Here is a better question:
What is the best way to deliver information to my customers?
Unfortunately, this is also a hard question to answer, and the answer changes from year to year. Right now, we have a lot of customers looking at ePub output. Two years ago, browser-independent web help was hot. Next year, it’ll probably be HTML5.
If you don’t know what deliverables I need, and you expect the requirements to change, how can you choose the best tool?
You can’t.
You need to reframe the question. A better question is:
How can I store information to support current and unknown future requirements?
The answer to this question is XML.
An XML-based workflow means that you don’t have to choose a winner among the various authoring tools—if your authoring tool goes away, you just take your toys (er, source files) and move on. You also don’t need certainty on output formats. Do you need XHTML, web help, HTML5, PDF, ePub, or a player to be named later? From XML source files, you can change your output formats as needed.
This approach is, of course, in direct conflict with the raison d’être of the various authoring tools. Software vendors have a vested interest in getting you locked into their particular tool for the long term. (And remember that consultancies have a vested interest in complex solutions that are too technically challenging for you to implement on your own.)
If you choose software with a high degree of lock-in, you give the software vendor the power to set your publishing strategy. Your strategy will be established based on the limitations of your toolset and the vision of the product team.
You must reverse this approach. Set your strategy first, then look for tools that support your strategy.
And don’t forget the power of the tech comm community. Some tasks look impossible on your own.
About the author
Julio Vazquez (@juliov27612)
Great post, Sarah. You definitely hit the nail on the head. As quickly as things change in this business, it’s imperative to implement a strategy that is flexible and allows you to move from solution to solution, if necessary. At this point, XML is the answer. (Though who knows what it’ll be 5 years from now?)
The best part of this post, though, is the reminder of the power for the tech comm community. Together we can deliver practically anything (except maybe a pizza).
Kai
Sigh… This is all too true and one of the few dogmas I afford myself as a tech writer: Put people (specifically my customers/users) before tools. Waaay before the tools.
I like Charlene Li’s POST sequence: People > Objective > Strategy > Tool (see my early blog post at http://kaiweber.wordpress.com/2008/06/30/top-6-ways-technical-communicators-can-benefit-from-the-groundswell/ )
An interesting middle ground (and one reason why we picked it) is occupied by MadCap with its open-file Flare editor. It’s not native XML, but rather XHTML (with an .htm extension), but otherwise open and (we hope) standardized enough, to allow us to move out into (even more) structured XML in the future…
Kai
@Julio: What!? Our community still cannot deliver a pizza!?? Sigh again… 😉
Larry Kunz
Sarah, this is one of the best blog posts I’ve read in a long time. (Pause for standing ovation.) I especially appreciate your warning about giving the software vendor the power to set my publishing strategy.
Julio, who says we can’t deliver a pizza?
<pizza crust=”thin” size=”large”>
<toppings>
<topping>cheese</topping>
<topping>sausage</topping>
<topping>mushrooms</topping>
<!– Hold the anchovies, please –>
</toppings>
</pizza>
Alan Houser
Message: Don’t focus on tools. But with a waving of a hand (“use XML”), the tools choice narrows to a handful. And those who deploy real XML projects know the sad truth — time spent configuring your tools is likely to be substantial. The “you can use any tool” mantra is only true with large investments of time and $$$.
And with an XML workflow, you also get to spend your own time and $$$ configuring your tool chain to produce these new output formats. And often the result looks like somebody crapped on a page.
Our profession has spent too many years dissing off-the-shelf tools and workflows (which can be used appropriately and effectively) for the “promise” of XML. While members of related professions aren’t afraid to use off-the-shelf tools to produce deliverables in appropriate output formats, optimized for the user and device, with a pleasing combination of design and content.
Sarah O'Keefe
@Alan: As Kai pointed out, there is a middle ground, which is to choose a tool that offers an easy transition into “real” XML in the future. I think perhaps Kai and I differ on how soon that transition may be needed.
I have worked on numerous “substantial” projects, but there are also shoestring XML implementations. I disagree that XML necessarily requires a huge investment.
XML is a storage format. If the output looks terrible, that is a failure of the implementer, not of the technology. (Or, it might be that the customer decided that they didn’t care much about look and feel. That is also not the fault of XML.) The XML toolchain does not have a monopoly on output that looks terrible. I’ve seen plenty of content that came out of commercial publishing tools that’s ugly.
To your third paragraph, I’m afraid I see the exact opposite. Many people in tech comm spend way too much time evangelizing for their preferred, beloved, “you’ll-pry-it-from-my-cold-dead-fingers” tool. And I don’t think I said that off-the-shelf tools were bad. What I said was that you should not allow tools (or tool marketing) to dictate your strategy. And I think it’s important to have XML in your strategy because there are just too many unknowns.
Camille Bégnis
Good point.
But there’s XML and XML.
Choosing a proprietary XML in a proprietary application won’t solve the issue. And even more, choosing an open XML (did I say Office Open XML?), is not a guarantee either…
Hopefully we have truly open standard XML for technical communication out there, let’s not fear to cite them: DITA and DocBook 🙂
Sarah O'Keefe
@Camille: Good point. Although even Bad XML is better than binary files…
Susan Modlin
Excellent post, Sarah. I’m facing just such a dilemma at my new company — figuring out how to deliver what the customer needs using a tool set I can tolerate for now and change out when the vendor’s goals and mine diverge.
Karen Lowe
I agree wholeheartedly with your post, Sarah. Having created what we consider to be brilliant output (and validated by our clients) through XML on a shoestring budget, I can attest to the fact that XML workflow is very possible.
I disagree with the idea that it’s too hard to implement an XML workflow. Yes, it takes time (to learn and experiment). It is work, after all. Yes, time means money to the company, but the long term benefits are worth the investment. Companies always invest in workflows, whether it’s during product development or management. It’s the cost of business. Historically, communication has been under-funded, which is more of a reason for companies to buy into the right approach, driven by the right business drivers.
My workflow may be fairly simplistic but what it can deliver is powerful. Due to employee turnover, our products are being supported by less people, something that couldn’t be done using proprietary tools with their plethora of manual processes.
Mark Baker
Bravo Sarah, well said.
I can understand where Alan is coming from: there have been many botched XML implementations created by people with much enthusiasm but little understanding of software architectures and structured data processing. It is indeed enough to give one pause about an XML solution. But the fault, as Sarah says, is not with XML, but with the naivety of those implementations.
You can, in fact, do a robust XML implementation with great output on a shoestring budget, if you know what you are doing. The tragedy is that so few people actually know the essentially simple set of principles that would allow them to do such implementations successfully. But the answer is not to throw up our hands and retreat of off-the-shelf solutions that will leave our content and our output in an obsolete state the next time the wind changes. The answer is to learn to use XML in a way that will make us independent of the changing seasons.
The real key here, though, is not simply XML. The key is to capture sufficient semantic richness in our content that we keep all our options open, so that when the wind does change, our publishing systems can simply trim their sails in a new direction.
Keeping your options open — that’s the key. Structure your XML so that it does not include any specific implementation details about formatting, organization, linking, etc., but instead captures the semantic information that can be used to implement all of those decisions in code. That way, when the wind changes, all you have to do is change your code to create output in the new fashion.