The Queen Follows the King

Gururaj B.S.

If you overhear a team of experienced technical communicators discussing or arguing with emotional rhetoric, you might realize that they are debating over the importance of Content vis-à-vis Tools.  It’s an interesting debate based on the fact that a majority of technical communicators today are focusing (sometimes more than necessary) on the tools in their jobs.  While tools are important, they don’t drive the direction of content, which is the king.  So you now understand who follows whom.

In the context of this article, I’ll emphasize how tools have started following the path of content in transforming the face of technical content being delivered to customers.  Let’s begin with a fundamental assumption that we all understand and appreciate the concept of single-sourcing, reuse, repurposing, and dynamic creation and publishing of content.  They may sound like a bunch of catchphrases, but they are ways in which content creators and publishers can maximize their Return on Investment (RoI) by improving their internal authoring and publishing processes.  I use Adobe products, so I’ve picked some features in Adobe authoring tools, which have been introduced or enhanced recently based on the emerging trends in technical communication.  The purpose of this article is not to compare authoring tools or their features, and I am sure other authoring tools or products not referred to in this article (read competitors) support equally good or even better features.

A few years ago, no one probably expected that technical communicators would consider or discuss XML because the scope of technical communication was limited to creating or producing a set of documents (what I call the run-of-the mill products), including user manuals, administration guides, online Help, release notes and so on.  It’s important to note that some or most companies were producing reams of printed documentation and shipping them to customers.  Legal binding or commitment is one of the reasons why companies still produce and ship printed books even if it’s not profitable for them.  However, people’s reading preferences are changing, and not many customers insist on printed documentation anymore.  In addition to the production costs, technical communicators creating content for printed books have to follow many complex production procedures, among many other things, such as the following:

  • Optimizing the PDF for print delivery
  • Setting crop marks and regions
  • Applying a different authoring template (sometimes)
  • Dividing content into multiple volumes, based on the length of content
  • Working with the print vendor or production department to produce high-quality PDF or PostScript (consolidated and separate files for each volume or chapter)
  • Creating covers and specifying binding types like shrinkwrap, cornerstitch, and so on

More importantly, writers working on print documents have to complete their documentation in all respects at least a month before the product release date, especially if the printed books and the online documents are released at the same time.  This situation becomes more complex and unmanageable if your content is translated into other languages and the localized documents are printed and sold to customers.  The same bunch of production procedures (some writers call them nightmares!) should be followed by the localization teams (read vendors).  If your company does not have a dedicated program manager to manage localization vendors, you might end up educating the localization vendors about production procedures and working with them closely to produce printed documentation.  What this means is that you as a writer will spend more time addressing production issues, and I do not endorse that approach.

When companies continued to invest in printed documentation, they probably needed a system to increase their writers’ productivity and decrease the cost of producing content separately for printed manuals and online documents.  In some companies, printed documentation cannot be done way with, and I am sure they will be more than happy to get rid of their printed documents.  Here is an anecdotal story about how printed books are used (or not used) by customers.  When a company conducted a customer survey to find out how their documentation is used by their customers, one of the customers invited the company to visit their office.  When a team of representatives went to this customer’s office, they realized that their printed books were used as door stoppers!  That’s quite useful, right?

Nonetheless, the need for reducing costs and increasing productivity resulted in single-sourcing, which simply means that a single source of content is published in multiple output formats.  For example, the source content in Adobe FrameMaker is published in HTML, CHM, or other help output formats.  This concept of single-sourcing has some obvious advantages, such as the following:

  • Consistency in content
  • No need for purchasing a separate license for an online Help tool
  • Opportunity to reuse a lot of existing content (user manual and online help, for example)

I see this trend as a key driver for Adobe to introduce a multitude of single-sourcing features in their technical communication products.  Before FrameMaker 8 was released, Adobe had almost dropped their “RoboHelp for FrameMaker” solution as they continued to support MIF import in RoboHelp.  Initially, MIF import in RoboHelp was not great because the mapping or association of styles used in FrameMaker documents wasn’t meant for styles to be used in HTML help topics.  In Adobe FrameMaker 8, in addition to improving the MIF import feature, Adobe introduced several new features, such as the following:

  • FrameMaker 8: Conditional text processing based on conditions with Boolean operators
  • FrameMaker 8: Filtering of content based on attribute values
  • RoboHelp 7: Importing ToC, Index, and Glossary from FrameMaker source content, setting pagination properties, defining a standard pattern for names of HTML topics converted from FrameMaker content, mapping FrameMaker styles to their RoboHelp peers, defining context-sensitive markers in FrameMaker and converting them into context-sensitive IDs in RoboHelp

In addition, to cater to the single-sourcing production requirements of technical communicators, Adobe introduced two new features in RoboHelp 7.  The standalone version of RoboHelp, whose license is sold separately, supports the addition of FrameMaker source files to a RoboHelp help project.  You are essentially copying the FrameMaker content into a help project.  In the other RoboHelp 7 offering, which was sold as a component of Adobe’s first-ever Technical Communication Suite, you can link to FrameMaker documents.  In a way, it’s similar to import by copying or by reference.  When you link a FrameMaker file, the file is referenced from its original location. If the FrameMaker file is moved from its original location, the FrameMaker file in the RoboHelp project displays a broken link.  This is a great feature, in my opinion.  Again, I want to highlight that it’s one of those features driven by emerging content trends.

Content practices and trends are dynamic, and it is good, in a way.  Users of technical content are embracing new trends like interactivity, context richness, ease of use and access, and relevance.  Paragraphs in an online help topic are making way for interactive simulations, video tutorials, or feature walkthroughs.  For example, Adobe Captivate enables you to develop simple movies and simulations, and you can save them as an SWF file.  You can insert such Captivate movies in FrameMaker documents (versions 8 or later) or RoboHelp projects (versions 7 or later).  This feature is particularly useful if you want to break the monotony of text-based content.

Now let’s consider DITA, one of the most widely used (misused?) terms in technical communication today.  I am not going to talk much about DITA because we keep hearing and learning about various aspects of DITA.  If FrameMaker claims to provide end-to-end support for DITA today, in FrameMaker 9, it is because of DITA’s popularity as a topic-based authoring methodology.  Why did Adobe bundle the DITA application pack with its FrameMaker product?  We all know the answer.  Topic-based authoring, such as DITA, is the order of the day, and it makes sense for the queen to sing a I-support-the-latest-trends song while following the king 🙂

Nowadays, we see global, geographically disbursed teams in technical writing departments.  Multiple authors sometimes work on different topics in the same book.  This trend led to the evolution of multi-authoring support and version control in authoring tools.  Although these tools don’t offer a full-fledged configuration management system, something like ClearCase, they are bundled with a simple Windows-like interface for basic source control tasks.  RoboSource Control, which is shipped with Adobe products, is a classic example.

Like a spring, beginnings of all things are small.  What start as simple content trends continue to transform into much bigger things like content management, workflows, dynamic publishing, automation, and so on.  This transformation is another reason why FrameMaker 9 offers support for out-of-the-box integration with a Content Management System (CMS).  I hope Adobe will soon offer a “mini CMS” with its FrameMaker or RoboHelp!  I am kidding, of course 🙂

In conclusion, I’d like to reiterate that the queen (tools) follows the king (content).  While the queen is important, the king is critical.  Therefore, I take this opportunity to urge all of you to focus more on Content while creating your documents.  The basic purpose of any tool is to simplify things, and a tool always has a limited set of features.  You can learn them on the job through experience.  Content, on the other hand, is critical, and it drives everything else. Period.

About the Author

Gururaj B.S. is a senior documentation manager at BEA Systems (an Oracle company).  He is the owner of Technical Writers of India (TWIN) portal, registered community, and mailing list.  He is a former president of the STC India chapter.  He is a weekend guest faculty teaching technical communication to undergraduate and graduate students at Christ University, Bangalore.  He has written content for IGNOU’s text book on Scientific, Technical, and Medical Editing for a PG Diploma course.

You can send him an email message at gururaj.bs@gmail.com.

One Comment

Comments are closed.