Scriptorium Publishing

content strategy for technical communication

A makeover for the DITA OT’s PDF Plugin

January 10, 2011 by

by David Kelly

Adoption of DITA involves a fair number of hurdles, not the least of which is getting nicely formatted output. Two kinds of output in particular present problems: tripane web help, because it is not provided in the DITA OT, and PDF, because the plugin is difficult to modify. My esteemed colleague, Simon Bate, has addressed the tripane help issue, so you can look forward to a blog post from him on that subject.

For this post, I am happy to announce that Scriptorium has developed an enhanced version of the DITA OT’s PDF plugin, providing an upgraded baseline for additional development. As I mentioned in a previous post, the PDF plugin is a good place to start, but an ugly place to stop. So we decided the least we could do was to make it a prettier place to start.

That same post also outlined a number of ways to modify the DITA OT. In writing about a few of the simpler things that can be done (and need to be done!) with the PDF plugin, we realized that XSL-FO and the PDF plugin are just difficult to deal with, in general. So we thought an upgraded PDF plugin might reduce the pain of starting with DITA.

Another reason for the makeover is that after helping numerous customers modify the DITA OT’s PDF output so it conformed to their standards, we found that there are many common requirements from customer to customer. Sufficient repetition of custom requirements eventually points to a new set of generic requirements.

We have also learned that the DITA OT “out of the box” contains of number of characteristics that need to be “fixed” every time we modify it. The absence of indexing when using the FOP processor is one such deficiency. (It’s no fault of the PDF plugin developers, however. FOP does not support some of the XSL-FO standard elements for index processing.) Another oddity is that when processing with FOP, table text margins inherit the current context’s left margin setting by default. With a few items like that, the PDF output could use a fair amount of “sprucing up” to be presentable. (Shades of Eliza Doolittle!)

Here are a few of the items that we have modified:

  • Added simple indexing support for FOP.
  • Modified handling of frontmatter to give the author control over the order of frontmatter sections.
  • Enhanced the headers and footers.  Various aspects of the content and format can now be controlled with variables in basic-settings.xsl.  Chapter and appendix labels and numbers can be added or omitted with a single control.
  • Modified the first pages for preface, notice, glossary, and index so their formatting is consistent with chapters and appendices.
  • Enhanced the font specification and various other format settings so they can be controlled in basic-settings.xsl.  Monospace fonts now have a different font size control than other font types.
  • Stacked the MiniTOCs on top of body text rather than presenting it side by side.  Side-by-side formatting presented issues when the top-level topic contained a body with text longer than a page.
  • Removed rules from titles to make them a more generic starting point for format changes.
  • Added support for the “expanse” attribute for figures.
  • Modified page-master formatting so offset margins can be controlled with two variables in basic-settings.xsl.
  • Added folio numbering for figures and tables when they are numbered on a per-chapter basis.
  • Provided system date functions to make it easy to insert a system date into headers, footers, or cover pages, as needed.
  • Modified index formatting to provide better control of keeps between primary and secondary entries.
  • Added control for the index entry indent size in basic-settings.xsl.
  • Enhanced the table of contents to provide formatting control from basic-settings.xsl; also modified alignment of numbers to prevent “wobble” in the stacking of the numbers.

The list includes a fair number of other minor enhancements. We have also developed documentation for the new controls and modified treatments. From what we have seen, publishers of technical documentation usually want some or all of these features when they get ready to publish their DITA source. We hope that this new version of the PDF plugin provides a more manageable entry point to DITA PDF publishing. If you are interested in learning more about the modifications, or have specific requirements that I haven’t mentioned here, give us a shout. (Or, if you aren’t within a couple of hundred yards, an email, comment, or phone call will work just fine.)

info@scriptorium.com
919-481-2701

And lastly, not to neglect the entertainment tradition of this fine blog, let me illustrate with another successful makeover (and yes, by George, she’s got it!):

The state of structure, 2011

January 3, 2011 by

Happy New Year!

In early 2009, we did a rather extensive survey on structured authoring. We asked about plans to implement structured authoring, existing implementations, biggest mistakes, and the like.

It’s time to update the numbers and see what has changed in the past two years.
So, please take a few minutes to fill out our structured authoring survey. The survey should take approximately 15 minutes and will be open until the end of February. Two lucky participants will each win a $50 gift certificate from amazon.com.

We will analyze the responses and publish the results in April. The results will be free for survey participants.

Please participate! There is very little research available on this topic. Your input will provide important information about the use of structured authoring in technical communication.

Update (January 4, 2011): In addition to participating, please help us get the word out by letting others know about this survey.

An update on The DITA Style Guide: it’s in technical review

December 16, 2010 by

Here’s a quick update on Tony Self’s upcoming book, The DITA Style Guide.

We won’t hit our original plan for a fall 2010 release date—especially considering fall officially ends next week (and don’t get me started on the wintry weather we’ve had here in North Carolina when it’s not even winter yet). However, the book is nearing completion. Right now, Tony has three well-known DITA experts providing technical review, and he plans to deliver content to Scriptorium right after the holidays.

We will then do the final production and release the book. At a minimum, we intend to provide print and ePub editions. We are considering a Kindle edition as well. If you’re interested in a Kindle edition, please let us know.

To get updates via email and to enter a drawing for a free copy when the book is published, sign up today.

Once more into the breach…

December 7, 2010 by

Back in June, we hired Ryan Fulcher as an intern. Ryan has done great work, and has now been promoted to full-fledged consultant. Congratulations to Ryan!

The bad news, from my point of view, is that we now must look for a new intern.

The internships is intended as a 6–12 month apprenticeship, which can then lead into employment as a consultant with us. We are looking for people who are interested in technical communication, want to explore the application of technology to complex publishing problems, and have excellent trouble-shooting skills. If this sounds this you, please take a look at the job posting for all the details.

Some thoughts on tekom

November 8, 2010 by

After a delightful week at the tekom/tcworld conference in Wiesbaden, Germany, I thought I’d capture a few impressions of the event.

First, it’s worth noting that tekom is really several events in one:

There’s the German tekom conference, the parallel English tcworld conference, and the annual general meeting of the tekom association. If you attend U.S.-based conferences, you’ll recognize some of the presenters in the English sessions. But in addition to the Usual Suspects (and I include myself in that category), tekom provides unique additional perspectives.

This year, the event featured a track on technical communication in Asia. I attended two sessions in this track:

  • DITA in Japanese Technical Communication. Satoshi Kuroda of Information Systems Engineering, Inc. presented the results of a DITA Working Group of the Japan Technical Communicators Assocation. This was interesting both because of the subject matter and because of the use of simultaneous interpretation from Mr. Kuroda’s Japanese presentation into English. To summarize, the working group recognizes that Japanese manuals tend to be highly visual, and this is difficult to implement in DITA. Thus, there is some concern that DITA structure might not be a good fit for the requirements of the Japanese market.
  • Trends and live samples of Electronic Manuals in Japan and Korea. This was another interesting session, presented jointly by Mr. Kuroda and Yang-sook Kim of HansemEZUserGuides in South Korea. Based on the title, I expected a variety of more-or-less interactive PDF files, but it turned out to be a discussion on online content. Mr. Kuroda and Ms. Kim showed examples of online content, including a rather spiffy series of short videos created for the Galaxy S smartphone. Interestingly, the video was created in addition to and not instead of text-based documentation. The target audience was “older people, in their 40s” (groan) “who had never used a smartphone and needed some extra help.”

The interpreters did a great job of translating technical content into English. That said, there were some inconsistencies. There were actually two interpreters working in 15-minute shifts. One interpreter spelled out any references to our favorite XML standard D-I-T-A while the other one said “DITA” as a word. In Japanese, the presenter was using “DITA.” There were also repeated references to “context writing” (which also appeared on the English-language slides) as contrasted to “topic writing.” I’m still not sure exactly what this meant, although I think it was “writing with context,” which would probably be narrative writing.

Dieter Gust of ITL delivered a great session on what is required for high-quality technical content. His “three pillars” are understandability, usability, and good process. This year’s presentation focused on usability and how to make usable content. Meanwhile, Mr. Gust is working on a unified model. You can find it, in German, on page 13 of this PDF file. Usability, he argues, is determined by the following factors:

  • Document organization
  • Typography
  • Navigation support
  • Orientation support
  • Reading support
  • Learning support
  • Search and find

(Interestingly, this matches some of what I discussed in my presentation as the QUACK model: quality, usability, accuracy, completeness, conciseness. You can find more details in our white paper on managing in an XML environment.)

Audiences at tekom in the English-language sessions are typically more reserved than audiences in North America. Non-native English speakers make up the majority of the audiences, and they are perhaps more comfortable listening to a presentation than formulating a question on the fly. But I believe that there is also a cultural factor at work.

I was delighted to meet several Twitter friends face-to-face for the first time. I also renewed acquaintances with tekom regulars that I had met on previous trips. The opportunity to build and strengthen these ties is one of the primary reasons that I attend conferences.

On Saturday, I went into Mainz with a small group (mostly those of us waiting until Sunday for reduced air fares back to the U.S.) We visited the Mainz Cathedral, the market, and perhaps the most relevant possible cultural site for a group of technical communicators—the Gutenberg Museum.

The museum houses a variety of printing presses, book binding information, several Gutenberg Bibles, and numerous other early books. It is certainly worth a trip for anyone at all interested in publishing. You should be aware that some of the signage is only in German. Nonetheless, seeing a replica of Gutenberg’s letterpress at work requires no translation. The docent pointed out that it took approximately three years to hand-copy a single book before Gutenberg. Gutenberg then produced 180 bibles in a three-year time span.

After seeing a huge variety of beautiful books, with hand-illumination, inset woodcuts, drop capitals, and other lovely designs, working in DITA seems suddenly less compelling. Our theme for the day was, “oooh, pretty. Can’t do that in DITA…”

[Updated November 8, 12:35 p.m. EST to correct typos and capitalization issues.]

The ePub has landed! The ePub has landed!

June 24, 2010 by

Our Technical Writing 101 book is now available in an ePub edition. You can purchase it from our online store or get it from Apple’s iBookstore.

Kudos to Ryan Fulcher, who spent his first weeks here immersed in the niceties of FrameMaker to XHTML to ePub. I think he’s still speaking to me.

The ePub edition is priced at $19.99 in our store and available worldwide. Via the Apple store, it’s $19.99 in the U.S., €13,99 in France and Germany, and £12.99 in the United Kingdom. (And yes, we realize that there’s an opportunity for currency arbitrage here. We can’t make the prices match exactly.)

The ePub has all the content from the original print and PDF editions. Cross-references are live, and we did some work to make the content look good in a variety of ePub readers. The file clocks in just under 4 MB, which isn’t too bad for 328 printed pages with lots of graphics and tables.

Are you interested in ebooks? Are you already reading them? What book would you like to see as an ePub next?

Purchase Technical Writing 101, ePub edition

Increase your DITA literacy with The DITA Style Guide

June 18, 2010 by

To help technical communicators get a grasp on all the elements and attributes in DITA, Scriptorium Press will publish The DITA Style Guide: Best Practices for Authors by Tony Self, founder of Hyperwrite and chairperson of the OASIS DITA Help Subcommittee.

  We plan to release printed and electronic book (ePub) versions this fall.

Sign up for updates on The DITA Style Guide

Whether you’re evaluating DITA, just getting started, or are already creating content, this book will help you figure out the best uses for the elements and attributes in the DITA structure. Speaking from personal experience, I wish I had this book years ago. Trying to determine when to use which element isn’t as straightforward as you’d think, especially when you’re new to DITA. Although the DITA language specification is helpful, it provides little background or context about the reasons for using particular elements (and frankly, it makes for dry reading).

That’s where Tony’s book comes to the rescue. The DITA Style Guide will offer practical information and real-world examples, as shown in the following excerpts:

______________________

What Element for Keystrokes?

The uicontrol element should be used when describing keys on a keyboard, and the userinput element for describing keystrokes that the user must input. …

It is not immediately obvious in DITA what element should be used to mark up keyboard keys, such as Enter, Ctrl and Backspace. The best approach (without resorting to specialization) is to use the uicontrol and userinput elements, depending on context.

When describing keys on a computer keyboard, use the uicontrol element. For example:

<p>Use the <uicontrol>Tab<uicontrol> to move from field to field.</p>

Note: Do not use the shortcut element; this element is intended to identify keyboard shortcuts in descriptions of user interface controls in windowed applications.

When describing a series of keystrokes that the user must input, use the userinput element. For example:

<cmd>Enter <userinput>1234</userinput>, then <userinput>Tab</userinput> 
to continue.</cmd>

Link Text for Relationship Tables

To control the text displayed in links automatically generated from the relationship table, a linktext element must be added to the topicmeta for the topicref.

If you want the link generated by a reltable to have a different title from the linked topic itself, you may think the technique would be to use a navtitle attribute in the topicref element. However, that doesn’t work.

The technique to use is to add a topicmeta element to the topicref, and include a linktext element containing the name of the link text. The example below shows the technique:


<topicref href="foo.xml">

  <topicmeta>

    <linktext>Replacement text</linktext>

  </topicmeta>

</topicref>

______________________

 

The printed book will be available from online bookstores all over the world, and the electronic book will be distributed through Scriptorium’s online store and other electronic book retailers.

Sign up if you want to receive emailed updates about the book’s status and release date. We’ll send you occasional messages about the book, and you’ll also get exclusive sneak peeks at content and a chance to win a free copy when the book released.

Consulting without commitment

June 10, 2010 by

engagement ringHiring a consultant can be intimidating. The RFP. The proposal. The prenuptial, er, contract agreement. The budget.

Sometimes, you just need a little bit of help without all of the craziness. For this, we have our new “instant consulting” service.

We have dispensed with all the bells and whistles. You buy as little as an hour of time through our online store. We schedule a mutually agreeable time to discuss your issue. You send any relevant information ahead of that time. At the specified time, we connect by phone (or Skype) and web meeting and go over your topic.

Instant consulting could work for a variety of situations, but we see it as especially helpful for these scenarios:

  • Discussing the best strategy for your publishing workflow.
  • Reviewing a strategic plan for your publishing workflow before you present it to upper management.
  • Getting advice on how to handle a specific management challenge.
  • Reviewing vendor proposals or helping to develop big-picture requirements.

We are open to other assignments that are of limited scope.

The cost is $300 for an hour; $1000 for four hours. You can buy in our store.

Of course, we continue to offer Big Project Consulting for larger engagements.

Free to a good home…industry research

May 12, 2010 by

In early 2009, we did some research on XML adoption rates and collected the results in a fairly lengthy report. Here is the summary:

In early 2009, Scriptorium Publishing conducted a survey to measure how and why technical communicators are adopting structured authoring.

The survey received 616 responses. 29 percent of respondents indicated that they had already implemented structured authoring. Only 16 percent indicated that they do not plan to implement structured authoring. The remaining respondents were either in the process of implementing structured authoring (14 percent), planning to do so (20 percent), or were considering it (21 percent).

Content reuse and document consistency were given as the most important reasons for moving to structured authoring followed by the cost/effort of developing content.

The Darwin Information Typing Architecture (DITA) is by far the most common structure being implemented. Use of DITA did not correlate with lower implementation cost.

A strong majority (67 percent) of respondents who indicated that they did not plan to implement structured authoring gave cost and time of implementation as the reason.

The most common authoring tools reported are Arbortext Editor, Adobe FrameMaker (structured), and JustSystems XMetaL. SynchRO Soft oXygen ranked well among DITA implementers.

You can get the whole thing on our white papers page.

It’s Technical Writing 101′s birthday, but YOU can get the gift of a free copy

May 11, 2010 by

It’s been a year since we released the third edition of Technical Writing 101, and I’d like to thank readers for offering us positive feedback on the new edition. I have to admit it’s gratifying to read comments such as this one from Peg Mulligan:

The discussions on Structured Authoring with XML, and Web 2.0 and Technical Documentation, are among the most concisely written, best stand-alone explanations that I have seen on these subjects.

To celebrate the third edition’s first birthday, we’re giving away a printed copy. Also, we have just five copies left of the second edition, and we will give the winner one of those copies, too. It will soon be a collector’s edition! (Yeah, right.)

Enter the drawing

The contest ends on Wednesday, May 26, so enter soon!

We owe special thanks to the many instructors who have used the book to educate new technical writers. If you teach technical writing and would like to review Technical Writing 101 for your classes, contact us at books@scriptorium.com.