Category Archives: Authoring applications

Our June 2012 Meeting: “Hands on with EPUBs – Mini-Workshop,” with Scott Prentice

Those wise and fortunate enough to attend this meeting left appreciating a learning experience one likely would have to travel to an STC conference to obtain. Again, Scott Prentice shared his considerable depth of understanding of the technical details underlying the words we read on the surface, and in the case of EPUB, we got to look under the hood and see how the various components of a document are related and stitched together.

(For the what, why, and how of EPUB — yes, ALLCAPS are back in fashion now — see Scott’s previous presentation.)

For the deconstruction process, we downloaded an ebook of one of my favorite authors, one E. A. Poe, and proceeded to deconstruct it with the oXygen XML editor. (Ever see the decoder table in “The Gold Bug” in XML?) A trial license is free for a month, and anyone interested in seeing how an EPUB document is constructed is encouraged to do the same.

With more and more existing information likely to be repurposed for mobile appliances, it will not hurt to become more familiar with this evolving publishing technology, perhaps the hottest thing since movable type. Standards are still evolving, with the powerful HTML5 standard still more or less on the horizon, and EPUB2 more reliable than EPUB 3. (You can download for free some great resource ebooks from look for “What is EPUB3” and “HTML5 for Publishers.” You can inspect the mysterious workings of these well-formed publications with oXygen, or even the free Sigil, which is also a ebook good reader.

As for ebook readers, Scott provides a good list in his meeting notes. There are many other goodies in those slides, so take a look. If you are interested in this growing area of doc expertise, Scott will be glad to explain.

Our July 2011 Meeting: “ePub: What, Why, and How?” with Scott Prentice

Scott Prentice, chapter webmeister, president of Leximation, and all-around FrameMaker guru, brought us up to date regarding the latest developments in electronic book publication standards. With the current proliferation of portable Internet devices, the savvy tech doc specialist may want to be aware of the issues involved in converting source documents to those that are readable, usable, and attractive on small screens.

The standard is “EPUB,” which Scott prefers to render as “ePub.” It is just another of many eBook formats, such as MOBI, DJVU, PDF, HTML, and TXT, that has evolved through time to meet user needs. ePub specifies the format and structure of the deliverable, much like a CHM, HLP, PDF, or HTML file does, and it requires both an application and a device to render the content for viewing. The underlying format is XHTML and CSS, with all components, such as content, images, and navigation, invoked from a single header file. Digital rights management (DRM) may also be included. The real wonder of it all is that content flows to fit the screen of the device on which it resides (to varying degrees of quality, as we will see later).

The ePub specification is maintained by the International Digital Publishing Forum (IDPF), and ePub 2.0 became an official standard in September 2007. (The original Open eBook standard of 1999 was actually developed for audio files and accessibility.) ePub 2.0.1 is the current stable build, and there is already a 3.0 draft. ePub comprises the following specifications:

Open Publication Structure (OPS): a standard for representing the content of electronic publications

Open Packaging Format (OPF): defines the structure and semantics as well as the mechanism by which OPS components are related

Open Container Format (OCF): (Seriously, Officer! the ePub was closed!) defines the mechanism by which all components of an electronic publication are packaged into a single deliverable (a ZIP archive)

So what are the many advantages, and why care?

The number of dedicated eBook readers is expected to exceed 11 million units by the end of this year, and the ePub format is supported by all readers and applications except the Kindle. A particular advantage of the format, in an age of vanishing trees, is that it is well suited to content that has limited life span — such as those 15-lb. programming manuals that are soooo last week. Rendered by a variety of conversion tools, ePub format works best for linear content, although reference material can use this approach as well.

It’s relatively cheap to provide instant gratification with this format. The user can search, add bookmarks, and annotations, and the content is very portable. But beware the downsides.

Tables more than a couple of columns wide can be disastrous on small screens. Links do not always work. Compliance with the standard varies highly, with no approach fully compliant. Indexes are not supported (although it is possible to create one as a page with links).

And as we noted earlier, renditions vary greatly (and can be truly extraordinary). Scott presented views of three different readers for the same content, and the differences were striking. As you will need tools (hand rendering is possible but not recommended), be sure to test drive a variety of applications to see which does the best job for your target devices. Scott presented an example of a specification document that he had converted, and it was very attractive and usable on both an iPhone and an iPad.

Enough for this overview. Now see the presentation summary that Scott provided and do your own exploration. Then head to the ePub for an ePint and let it all sink in.

Our October 2010 Meeting: Publishing PDFs from DITA

At our last meeting, Scott Prentice, chapter webmaster and president of Leximation, Inc., presented a concise summary of the motivations and issues involved in using the Darwin Information Typing Architecture to produce PDFs. Why use DITA at all? By using XML to author in a topic-oriented structure, DITA lets you rearrange topics and reuse them easily, depending on the deliverables (paper? PDA? online help?) you want from the same source material.

Isn’t this a wonderful thing? Yes, it can certainly be, depending on the nature and size of the enterprise and the amount and different types of content required–but it is not for everyone, and you had better choose your approach carefully from the start.

The great value that Scott provided in our online session was in detailing the various options. How much “manual” control to do you need (and have the technical resources to support)? How much built-in support do you need (and have the budget for)? What is the volume of your output and projection for future need, and how many “seats” do you need licenses for? These are just a few of the questions you must ask before heading down the DITA direction, because what looks like a simpler, more affordable approach at first could turn out to be an expensive, painful trap.

For a concise listing of the products, prices, and particulars of a variety of commercial DITA applications, you can’t do much better than review the brief summary of DITA issues that Scott has provided. Read it and be wise.

Our July 2010 Meeting: A Tour of Virtual Worlds and How They Impact Technical Communicators

In this online-only event, Mike Ziegenhagen shared his growing expertise–and most of all his enthusiasm–ror the expanding sector of virtual world applications. Many are by now aware of Second Life, but Mike documented an application from Forterra Systems called OLIVE ™, an “online interactive virtual environment” that offers the security sorely lacking in the standard, free version of Second Life (OLIVE can be seen as “Second Life in business suit”). His experience with the team was also a great opportunity to work with both artists and actors, to achieve the best possible renderings and life-like actions of the avatars. Verisimilitude is more and more critical to success. Mike also gave a brief tour of Blue Mars, a 3D social networking application, based on high-definition game technology, that is definitely worth exploring.

There are additional applications for hosting secure virtual meetings: Venuegen can be “rented” for under $100/mo. for ten people or so, and 3DXplorer offers an enterprise beta version. Both are browser based. Also, Second Life Work offers an application-based approach for those willing to buy.

Why bother? It turns out that business are seeing the advantages to hosting so-called hybrid events and conferences. Participants who want to meet in meatspace continue to do so, while those distributed around the world appreciate the advantages of entering the virtual world. Indeed, perpetual virtual environments are turning out to be profit centers. Not only that, but they can be really fun (as long as you don’t get lost in layers of consciousness, Inception-style, so to speak. It is actually not all that hard to get lost. But fortune favors the brave and the curious. With increasing bandwidth and video processing power for less and less money, it it not inconceivable to see virtual meeting places become more and more common. They can be used to unite family members, and they provide unique opportunities for training. STC is rumored to have a group (more detail to be provided when it is available), and you can always check out NPR’s Science Friday Second Life.

Next steps?

  • Do some research.
  • Explore some sites.
  • Download Second Life viewer and take if for a ride.
  • Get a good headset.
  • Have some fun.
  • The NorthBay Chapter is looking forward to playing around with this new medium, so stay tuned and let us know if you want to test the virtual waters. It is almost as if the spirit of the early days of computing were back again.

    Our June 2010 Meeting: Creating a Knowledge Base using MadCap Flare and Madcap Feedback Server

    Wendy Bidwell had long planned to present at our chapter but was now in Florida.  Would she accept our offer to present remotely using Acrobat Connect? Indeed, she took the plunge and all went very well, becoming our first formal telepresenter.  The commute and parking were much easier, despite the late hours for her.

    Her theme: How to use MadCap Flare in conjunction with MadCap Feedback Server to manage data in association with an online help project–improving communication among writers, customers, and employees.  So-called “out-of-the-box” applications just weren’t doing it, but Flare provided a great way to manage a knowledge base, while making it easy to export content to a variety of target output formats. Combining MadCap Flare with a Feedback Server to create a company knowledge base provides improved, interactive communication among writers, customers, and employees.

    Users can add comments and rate topics, and writers can analyze user searches. This provides the same kind of valuable information one would have to obtain from talking to customers and support personnel and conducting usability studies.

    For detailed instructions on installing and configuring MadCap Flare and MadCap Feedback Server in this context, see Wendy’s document. Other servers are also supported.