Publish High-Quality, Print-Ready DITA in less than a day

My first book went live this morning: Arbortext 101. It is also the first book about Arbortext that was not published by PTC.* Arbortext is an extremely simple XML authoring and publishing suite of programs. It's got an editor, a styling tool, a server-based publishing application, and a content management system. It's 20 years old this year. In my career, I've used nearly all of the XML/SGML tools out there. I like different tools for different purposes. I'm a big fan of the "right tool for the job" as it were. When I approached the project, I decided that I'd distill the 5000+ pages of technical documentation that gets published with the product into a short book that documents the best practices that we've developed over the 15 years as users and customers of Arbortext. A couple of things happened close together...

The inspiration

First, a friend and STC board member put together a self-published, short book for Kindle and remarked on how simple it was to do. Then, we had a strange year here at Single-Sourcing Solutions. Customers kept coming to us having gotten recently-delivered stylesheets and Arbortext implementations that were...so badly put together that everyone here was stunned. Problems had been built into the deliverables that had obviously been designed to benefit the consultant who had done the work, rather than the customer they'd done the work for. At Single-Sourcing Solutions, we're customers, just like our customers. We're not ex-PTC, ex-Arbortext employees or developers. We have the hard-earned knowledge that only a user of a product -- someone who depends on the product working in a mission-critical situation -- can develop. We are also well known as the consultants who empower their customers rather than throwing projects over the fence at them. We teach our customers what we've done and why we made the choices we did. We want them to be able to make changes going forward.  And then another customer came to us with the same situation. And again. And again.

It certainly inspired me to get started writing.

What publishing format do you pick?

I figured that the very least I could do would be to get the Kindle book written. We could publish it ourselves and skip the overwhelming uncertainty of shopping for a publisher. The book would be out there and maybe it would improve everyone's lives or at least give them some way to evaluate the quality of the product they'd been delivered. (Hey, maybe the consultants who were delivering bad work product would read it too?) Amazon has made it easy to self-publish to Kindle. They've written an excellent guide to help: "Building Your Book for Kindle" and we've given presentations on the key tips. You still have to do the writing and that will take longer than you expect. Once that is done, getting the ebook constructed and approved on Amazon is very straight-forward. Wouldn't you know, though, that as soon as I announced the book was available as an ebook, I got a hundred and one requests for print. It seemed like everyone preferred a print copy. Amazon has you covered there too. In a partnership with CreateSpace, you can arrange for your book to be printable on demand. They even have professionals who can help you with the manuscript layout, cover design, and editorial tasks. All the benefits an established author would get with a publishing house.

Hey! I already have the tools I need to publish DITA

I use Arbortext. I have professional publishing software at my fingertips. So I converted my manuscript to DITA and created an Arbortext Styler APP-based stylesheet. APP is short for Arbortext Advance Print Publisher, the rendering engine that's the basis for Arbortext publishing. APP is used for magazine and periodical publishing. It's used for textbooks. It's used by print publishing houses around the world. I could do this myself too! It took me less than 8 hours to create a print-ready PDF suitable for publishing a paper book. In those 8 hours, I did the following:

• created a new custom environment for my new project
• converted my manuscript to DITA (including some cleanup tasks such as adjusting markup so that the "Expert Tips" throughout the manuscript were identified as note/@type="tip")
• created a brand new Arbortext Styler stylesheet
• customized the stylesheet to my preferred look and feel (color, page size, page layout, headers, footers, TOC, etc)

And out popped a print-ready stylesheet that, when I uploaded it to CreateSpace, didn't have a single issue — from a PDF construction perspective — that would affect a print run. They did notice that I had low-res graphics (screenshots that I'd done with Paint), so I had to reshoot those. But otherwise? Not a single issue. CreateSpace is preparing a galley copy for me to see before the print version of Arbortext 101 goes live. So it'll be a couple of weeks before it gets added to the product page. That part can't be avoided either. They need to print it, mail it to me, give me time to review it, and that all takes time.

Overall, an incredible experience all around

Styler and Arbortext's DITA support has become so tight, that it took me less than a day to both create a stylesheet, convert my content to DITA, and publish. If I'd tried to write an XSL-FO from scratch (and I'm an XSL-FO veteran who first learn from Ken Holman back in 2002), I could not have done the same thing in the same amount of time. Finally. Finally! After 15 years, the goal of being able to deliver pretty, print-ready, high-quality PDF, without a lot of programming and delay is here. Hasn't this been what my whole career has been about? I'm amazed at the speed I was able to do it, even though I know that this is what we've all be driving toward this whole time!

Get Arbortext 101 today

Find out more about the Arbortext product suite. Get  your copy of Arbortext 101, and DIY!

P.S. A how-to guide for creating the stylesheet to publish DITA

Updated: 2016-10 I've already delivered on Arbortext 102, a step-by-step guide for creating the stylesheet necessary to doing exactly what I just described: Best Practices for Creating Arbortext Styler stylesheets. Get your copy today and get started!

* Only one other book came close to being about Arbortext. JoAnn Hackos wrote "Introduction to DITA A User Guide to the Darwin Information Typing Architecture Arbortext Edition", but it was a book about DITA that only used Arbortext for illustrative purposes.

Note: When you purchase something after clicking links in our articles, we may earn a small commission. Read our affiliate link policy for more details.