An incomplete puzzle: DITA OT stylesheets
posted by ToolSmith

A recent post on the dita-users Yahoo group asked how to customize the DITA OT stylesheets in view of the fact that there isn't much documentation available.

From my work customizing and otherwise perverting the DITA OT, I can sympathize with these frustrations. When I started investigating OT customizations, I found many well-crafted tutorials on how to customize and specialize the OT.  These were a great starting point, but they only got me so far.  In its current state, the documentation is an incomplete jigsaw puzzle; the trees and buildings are filled in nicely, but the sky is still waiting for someone with patience.  (Block that metaphor!)

Because there is no documentation available at the individual template level, you need to reconsider the task at hand.  I look on it as debugging, decoding, or sleuthing. With that in mind, I find the following to be very useful:

• Find a good visual grep-like utility. I use AgentRansack, a free version of FileLocator Pro (it's free and amazing). This enables me to locate all files that contain a particular class identifier. The visual aspect of the tool allows me to see the context quickly.
• Use a programmer's editor that supports XML and XSL. We use Oxygen. Not only does it help check validity and closes tags automatically, but it also provides a handy sidebar that lists the templates and their modes.
  
• Liberally spread <xsl:comment> or <xsl:message> directives through the stylesheets you're examining. That helps figure out where you are. Use <xsl:value-of> or <xsl:copy-of> to figure out what you've got.
• Once you've figured out what happens in one of the OT templates, add comments. Now the next time you come back to it, you won't waste time.
  

Probably the best form of documentation that the OT could provide here is additional comments in the stylesheets, particularly about the order of processing.  I find I add many comments about where to find the template that handles nodes from an  <xsl:apply-templates> directive.

One further note.  On Tuesday, September 23, I'll be presenting the third of our "Best Practices in Structured Authoring and Publishing" joint Webinar series with JustSystems.  In this presentation I'll describe a number of approaches you can use to customize DITA OT output.  For more information, visit the JustSystems web site.

Labels: XSL DITA OT customizing specialization

10:12 AM Permalink | |

 
Learning the DITA Open Toolkit
posted by Sarah
(Scriptorium Publishing is a JustSystems Services Partner.)

Simon Bate's webinar, An Overview of the DITA Open Toolkit, is now available. This event was jointly sponsored by Scriptorium Publishing and JustSystems. The recorded version is available here (registration required).

During the presentation, we did some audience polling.

Are you currently...? (choose one)

• 31%, Using XML
• 32%, Transitioning to XML
• 16%, Planning to transition
  
• 17%, Considering a transition
  
• 3%, Not considering it at all
  

If you answered "using XML" above, what content model do you use? (choose one)

• 59%, DITA
• 0%, DocBook
• 1%, Other publicly available
  
• 10%, Developed in-house
  
• 3%, Not considering it at all

Probably not too surprising that DocBook scored 0% in a DITA-specific presentation.

I liked the last poll:

What formats do you currently or plan to publish to?

• 50%, print
  
• 92%, PDF for download
• 49%, web site
  
• 79%, online help
  
• 18%, other
  

92% are delivering PDF. We very frequently have people tell us that they "don't need print," but it nearly always turns out that they do need PDF. We operate on the general assumption that all of our customers are going to need PDF at some point, even if they don't think so, and I'm happy to see at least one data point that supports this line of thinking.

The problem, from our customers' point of view, is that producing nice PDF from DITA content is really quite challenging. (From our point of view as consultants, this is not necessarily a bad thing.) What makes PDF so challenging? Basically, you are reverse engineering your layout engine (think FrameMaker or InDesign) in the XSL-FO programming language.

Simon's presentation provides an excellent introduction to the Open Toolkit, which many find quite intimidating. This was apparent from some of the questions and comments that Simon got:

Is there a GUI for OT that could be used by documentation production staff rather than command line?

I haven't typed a command into DOS in twenty years.

What's the difficulty level of using OT to get HTML output that is more professional-looking, like a WebWorks HTML generation?

Can you please define the purpose of ANT files?

It's worth noting that running the Open Toolkit is vastly less difficult than configuring the Open Toolkit. The person doing the configuration work will need to understand Ant, type DOS commands (!), and rework the default transformation templates to produce the desired output. The person generating output with the configured OT will need to type in one command or just double-click a batch file to start processing.

Many of our customers have turned to us for the Scary Configuration Bits. If you're looking for help, keep us in mind.


This session was the second in a series of three webinars we are doing jointly with JustSystems. The last session, on September 23, will provide more details on customizing the DITA Open Toolkit. The webinar is free, but advance registration is required here. Hope to see you there.

Labels: dita, presentations, xmetal, xml

3:41 PM Permalink | |

 
A Day in the Life....
posted by Loring
Here's an inside peak at a day in the life of a Scriptorium employee:


http://xkcd.com/208/

But wait, there's more...a t-shirt!


http://store.xkcd.com/

Ladies, check out the regular expression skirt, too. The code is printed upside down for easy reading while sitting.

Labels: humor, regular expressions

1:30 PM Permalink | |

 
Adding color commentary to white papers
posted by eDuty
When Scriptorium wrote on Web 2.0 back in April, we mentioned creating HTML versions of our white papers. Those papers are now live, ready for your ratings and comments.

You can link to them below or from our white papers page.

Friend or Foe: Web 2.0 in Technical Communication

Structured Authoring and XML

Managing Implementation of Structured Authoring

Is DITA Right for You?

Integrating XML and FrameMaker

Labels: comments, ratings, web 2.0, white papers

1:06 PM Permalink | |

 
Surprise! It's about quality.
posted by Sarah
(Scriptorium Publishing is a JustSystems Services Partner.)

On Monday, August 18, I delivered a webinar on making the transition from desktop publishing to structured authoring. This event was jointly sponsored by Scriptorium Publishing and JustSystems. The recorded version is available here (registration required).

During the presentation, we did some audience polling. And here, there were some surprises for me. We asked:

How are you authoring content today? (choose any)

• 31%, Word
• 14%, HTML authoring tool (i.e. Dreamweaver)
• 69%, Desktop publishing tool (i.e. unstructured FrameMaker, PageMaker, InDesign)
• 20%, Help authoring tool (i.e. RoboHelp, Flare, AuthorIT)
• 37%, XML authoring tool (i.e. XMetaL or structured FrameMaker)
  

Nothing too shocking here, although I was a little surprised to see such a high number for XML authoring in a session on how to transition to structure.

In poll 2, things got very interesting:

What is the level of authoring at your organization? (choose one)

9%, #1. Chaos. No consistency
4%, #2. Documents match on paper
16%, #2.5 We have a template and sometimes follow it.
60%, #3. Template-based authoring. Repeatable process for creating consistently formatted documents
10%, #4. Structured authoring. Programmatic enforcement of required organization

When I ask this question a roomful of people, it's rare to get an admission of level 1. I've never seen anything like 10 percent of a live audience choose number 1. Perhaps the relative anonymity of a webinar is a contributor?

We asked some questions about skillsets with nothing of particular interest to report. Finally, we inquired about the business driver for structure implementation:

What is your critical business driver behind looking to improve how you manage content?
(choose one main driver)

10%, Speed up time-to-market
30%, Improve satisfaction with customer-facing documentation
3%, Comply with regulatory requirements
12%, Reduce localization cost
27%, Improve staff productivity
13%, Reduce production cost
4%, Other

The surprise here was that, at least in this group, the most single common response was a quality answer ("improve satisfaction") rather than a cost-reduction answer.


My session was the first in a series of three webinars we are doing jointly with JustSystems. The next two sessions will focus on the DITA Open Toolkit. Simon Bate, Senior Technical Consultant with Scriptorium, will deliver an overview of the Open Toolkit on August 26 and a session on troubleshooting and customizing the Open Toolkit on September 23. The webinars are free, but advance registration is required here. Hope to see you there.

Labels: change management, presentations, xmetal, xml

11:27 PM Permalink | |

 
Free books are gone
posted by Alan
We've given away all the copies of the Technical Writing 101 book. Thanks for all the responses.

We are happy the books are going to readers instead of the recycling facility!

Labels: book, technical writing

1:16 PM Permalink | |

 
Yet more free copies of Technical Writing 101 (first edition)
posted by Alan
As I mentioned in an update to my post yesterday, we located more copies of the first edition of Technical Writing 101. We have divided this lot into four batches, each of which has nine or ten books. If you'd like one of these batches, please contact me at books@scriptorium.com. We will ship the books to you at no charge.

Update: We have given all the books away. Thanks for your quick responses!

Labels: book, technical writing

9:14 AM Permalink | |