Design isn’t free
The mantra of XML is that you separate content from formatting. Authors do content; formatting happens later. During a panel discussion at last week’s (excellent) UA Europe conference, I realized that this is only half the story.
Too often, the decision to move to XML is made without any consideration of output requirements. With desktop publishing (DTP) tools and help authoring tools (HATs), a moderately competent computer user can control the look and feel of the final output. A lot of XML implementers assume that their DTP and HAT skills will carry over into XML publishing. Halfway through their project, they discover that XSLT, XSL-FO, and DITA Open Toolkit plugins have much more in common with programming than with traditional publishing tools.
And then the complaints start:
Why is this configuration so hard?
I can’t believe that there’s no GUI-driven tool for XML output.
This PDF output is really ugly!
Why should I have to learn XSLT, CSS, and Ant?
Boo-de-fricking-hoo. Anyone who pays even cursory attention to tech comm chatter or knows how to operate that new-fangled Google thing should observe in less than 10 minutes that XML publishing is technically challenging. I have absolutely no sympathy for those who didn’t discover this before they leaped into an XML project.
Expertise in traditional DTP tools or HATs does not necessarily transfer into competence with myriad XML technologies from Ant to XSL. But many organizations try to implement XML and cut corners on the output design phase. This leads to the widespread assertion that XML produces ugly output.
The default PDF output from the DITA Open Toolkit is certainly not very attractive:
U-G-L-Y
But it’s possible to change the formatting:
Acceptable?
The decision whether or not to implement XML should include an assessment of the XML publishing problem, and the costs associated with developing attractive output (in-house or with consultants). The fact that a new workflow requires new skill sets should not come as a surprise in the middle of the project.
(Ed. note: Weak attempt at linking the content of this post and highlights of trip to Dublin in the photos below.)
A few of the books needed for XML proficiency (or possibly the Long Room at Trinity College in Dublin) // flickr: unhindered
If the cost of creating attractive output from XML is greater than the benefits of moving to XML, then you either settle for ugly output or you do not move to XML.
These decisions should be made strategically, with a solid understanding of the challenges, and not in a mid-project panic.
You'll want to fortify yourself for marathon coding sessions. I recommend boxty. // flickr: infomatique
XSL coding is not everyone’s cup of tea. I wish just more people would realize this before deciding on their XML strategy.
About the author
Ben
Sarah,
What are your thoughts about the increasing possibility of using CSS3 to format XML source? We’re quickly approaching the point (if we’re not already there) at which, for some use cases, the print formatting capabilities of CSS are good enough to justify avoiding the complexity of XSL-FO.
Sarah O'Keefe
First, a disclaimer in that I’m not an expert in CSS, version 3 or otherwise.
The process of going from XML to any output requires (at least) two major steps: transformation and formatting. CSS3 could potentially address the formatting piece, but there’s still the issue of transformation. For DITA, transformation includes the processing of linked content (conrefs), applying conditional settings to filter text, and (for PDF) processing the map file to create a “merged” XML file from which a monolithic PDF is then created.
I think that transformation is what presents the more difficult technical challenge, so while you could possibly use CSS3 for the formatting piece, you would still have the upfront issue of transformation. A workflow based on XSL and CSS3 doesn’t seem *that* much easier than XSL-FO (which is basically XSL plus CSS anyway).
I do think that CSS selectors are often easier to understand than XPath expressions.
Scott Prentice
I agree with you 100%! However, just because you decide to use DITA to store your content doesn’t mean that you have to use the DITA Open Toolkit for publishing. There are lots of good reasons to use it, and it is a good idea to become familiar with it, but your old HAT and DTP skills can still be useful even after you move to DITA.
If you’re a Flare or RoboHelp user, you can import your DITA content (with varying degrees of success) into that program and generate your online Help like you used to. There’s also DITA2Go, a free tool from the makers of Mif2Go, that can generate many types of online Help without doing any XSL coding.
If you want nice PDFs, you can continue to use FrameMaker for publishing even if you’re no longer using it for authoring. All of your old template design skills still apply. You may need to learn some EDD and structure application concepts, but that’s far, far easier than XSL-FO, and will give you much nicer PDFs.
[shameless-plug] If you want to simplify the PDF creation process through FrameMaker, check out DITA-FMx from Leximation. This lets you set up a build process for each of your books so it’s easy to get consistent PDF output from your DITA map. If you want to automate this process on the desktop or as part of a publishing workflow from a CMS, you can use FMx-Auto. [/shameless-plug]
People need to realize that the decision to use DITA as the storage format for your content is just part of the story. It doesn’t mean that you can eliminate proprietary tools from your workflow. You still need an authoring tool (oXygen, XMetaL, FrameMaker, ??), and you may need to buy a publishing tool as well. If you’re using the DITA-OT for PDF, you’ll probably need to buy RenderX or Antenna House to generate the PDFs .. or, you can use FrameMaker (which you probably already own).
There are lots of choices here, so before heading down any path too far, be sure that you’ve really explored all of the options. Don’t get locked into one path that seems to be the least expensive, when in fact it may be the most expensive.
Cheers!
…scott
Sarah O'Keefe
Yes, I think the bottom line here is do your research.
Susan Modlin
Boo-de-fricking-hoo? Best neo-logism of the week!
Sarah O'Keefe
I’d like to take credit, but I’m pretty sure I heard it somewhere else… (upon further review, Google only returns 4 hits)
Frank Buffum
You need a “like” button for your posts, Sarah. In this case, for individual phrases. (b-d-f-h was my favorite, too…)
Erin
You didn’t need to coin it to deserve our thanks and praise (and fearful trembling) for using it here!
Debbie M.
You need to widen your search. It’s more often used without the “de” and with “freaken” instead of “fricken.” There are nearly two million hits when you search with the expletive that “freaken” and “fricken” alias.
Certainly gets the point across in any iteration.
Yves Barbion
I fully agree, professional design isn’t and shouldn’t be free. And indeed, if you want to get an acceptable PDF from the DITA Open Toolkit, you better prepare for some serious XSL-FO development work. The DITA Open Toolkit is a great publishing tool, but it is a “reference implementation”, which is often overlooked or misunderstood. But then again, there is more than the DITA-OT to get your DITA-sourced content published (but the design with these tools is not free either): http://bit.ly/dita2pdf
Gerrit Kuilder
I think that being able to code (xsl/css) and graphic design are separate skill sets. They are not found very often in the same person.
I have worked on a few Dita projects and have not met with many graphic designers that had created stylebooks, usually it was bits and pieces thrown together that looked nice to the people involved.
The solution would be to get a graphic designer involved, put together samples and requirements, let the graphic designer make mock-ups and a stylebook and then start coding.
Often this also requires authors to follow certain standards.
As a side note: look at the two illustrations in this post: different indents, different space between image and caption
Sarah O'Keefe
Your side note is a good example of something that would be prevented by automated formatting. Not sure what I did in WordPress to achieve such “interesting” results.
Jean Kaplansky
I’m still laughing.
But I’m a former professional stylesheet writer. 🙂
It’s not rocket surgery, people! The sooner you start, the sooner you fail, the sooner you panic, and “don’t wake up in a roadside ditch…” (for the US readers).
Put another way: “The sooner you start, the longer it takes.”
There are no shortcuts in XML! Just like “there’s no crying in baseball!”
Do the document analysis and figure out your business rules, and decide what your DTD should be _BEFORE_ you even think about letting a developer set a hand on the keyboard.
Do NOT even attempt to think about stylesheet specifications until you know what specific DTD or schema markup patterns you are going to use.
There is a reason this stuff is done, and professionals tell you not to skip corners – and it has way more to do with us wanting to see you succeed than it does with hourly consulting rates… Seriously… You pay how much for a consultant? And then you don’t listen to them? And then your project falls apart and you panic? Are people really still trying to get away with this? Aren’t there enough horror stories on Google about what _not_ to do?
**shakes head** I’m going back under the rock now.
Sarah O'Keefe
Hi Jean, I’m glad you were entertained. I found it quite cathartic myself. 🙂