From Postscript to XML and Beyond …

By Neil Perlin (with thanks to Spiderman)

In this article, I’ll discuss how changes in the coding used to create online documentation and help (“online content” from now on) have changed how technical communicators work. From that perspective, I’ll then look at the changes we can expect to see as XML and XML-based authoring tools enter the market and how to react to those changes.

Let’s start by reviewing the past.

From Word Processors to Online Help

In the early ‘80s, the technical writer’s main tool changed from the typewriter to the word processor. Technical writers suddenly had to deal with issues like file formats and format conversion among different word processors. But the focus was still the writing; the code that controlled the documents was hidden.

In the late ‘80s, Microsoft Word’s Rich Text format (RTF) spread as Word gained market share. But the RTF code would still have stayed hidden except for one twist – Microsoft used RTF as the code for WinHelp, Windows’ first native help format. Help authors who were creating WinHelp couldn’t use authoring tools like RoboHelp; they didn’t yet exist. So help authors had to hand-code using tools like Windows Notepad.

Effects?  The process of technical communication had jumped in complexity. Technical communicators/help authors suddenly had to worry about code syntax as well as content. Hand-coding ability became an indicator of an author’s machismo (or machisma, in many cases). Much of today’s hand-coding mystique dates from this era.

Hand-coding RTF is slow and typo-prone, so help authoring tools, or HATs, appeared in the early ‘90s. Today’s best-known HAT, RoboHelp, dates from that time.

Effects?  The HATs physically inserted the codes so help authors could, theoretically, go back to focusing on content. But early HATs were crude enough that authors still needed coding skills to fix problems or add features that their HAT didn’t support. So coding ability was still important.

By the late ‘90s, HATs had improved enough that authors no longer needed to know what was going on at the code level. WYSIWYG interfaces hid most of the code detail. Then Microsoft released HTML Help…

HTML Arrives

HTML Help set the stage for today’s development environment. It also reprised some problems of the RTF era, including:

• HTML was new and unknown to most help authors, just as RTF had been.
   
• The HATs had to catch up to the new technology. This forced early HTML Help authors to learn HTML and to create and edit files in tools like Notepad. Coding ability became crucial again.

Effects?  The need for coding ability returned. So did the perception that coding was the indicator of an author’s machismo/machisma. This again diverted authors’ focus from the content.

But the move to HTML added new problems:

• More technical complexity. Authors had to determine whether users had the right browser (if they had one at all) and the help mini-browser. This depended on the version of Windows that users had. In effect, help authors were getting involved with system configuration, normally IT’s job.
  
  The shift to HTML also meant that help began to resemble web sites. This meant that authors had to go beyond the usual Microsoft-centric, C: drive world to think about Linux users, Mac users, Netscape users, and others, who might be running help systems from servers instead of floppies or CDs. Get this information wrong and authors might pick the wrong help format or the wrong HAT.
   
• Greater development pressure. Online help had become accepted, even expected, in many products. This meant authors suddenly had to deal with time-to-market and ROI (return on investment) pressures. The unhurried freedom to experiment and play that authors had enjoyed only a few years earlier was gone.

Effects?  Technical complexity skyrocketed. The new HTML-based output formats were often confusing. (Was “Web Help” the same as “WebHelp?”) Standards and consistency were becoming important. Plus, as technical communication became still more technical, the nature of the writing began to change away from creativity. Authors who still viewed themselves primarily as writers began to dislike the increasing emphasis on technology. Some began to leave technical communication.

XML Arrives

HTML’s limits were clear by the mid-90s, and the W3C (WorldWide Web Consortium) released a replacement, XML (Extensible Markup Language), in the late 90s. XML has been used for eCommerce since the late ‘90s but has only hit technical communication in the last few years. In other words, we’re now moving into the next new era.

XML-based help is reprising the problems we experienced with HTML and RTF but with some new twists:

• XML is more confusing than HTML because XML is not a language. Instead, it’s a “meta-language” - a set of rules for creating languages. So authors may have to learn different XML languages depending on the markets they support. And, as with HTML, XML is new and unknown to many technical communicators.
   
• The HATs are trying to catch up with the technology, so early authors may again have to work at the code level. This situation won’t last long; WYSIWYG tools are already appearing. But the early tools won’t offer all the features that authors need, or have become accustomed to from their HTML work.
   
• More technical complexity. The different types of files involved in XML require a level of rigor that will be very new to authors accustomed to HTML. What’s the difference between well-formed and valid and how is that expressed in a DTD or XSD, for example?  How does a CSS render an XML file?  What’s a transform and how does it relate to the XML files?  And so on.
  
  Just to confuse things, the technology is changing rapidly. For example, schemas are replacing DTDs for syntax control. It’s important to understand the technical aspect of these changes, but also their effects on your strategy and documentation processes.
   
• Time-to-market and ROI pressures continue to rise, but with a new angle. Online content is moving into low-tech - hospitals, insurance companies, banks, etc. – as such companies start to abandon hard-copy. Authors in such companies are making the same mistakes that authors in high-tech did years ago. The difference is that low-tech authors don’t have the latitude that high-tech authors once did. The market pressures are too great. Yet the low-tech authors often don’t know where to turn for help.

And XML adds some new problems:

• The need for more rigorous writing methodologies, like structured writing. This will be a difficult change for companies whose culture doesn’t support rigorous writing standards, but it’s necessary to take full advantage of XML’s single sourcing power.
   
• More complex single sourcing. HATs have claimed single sourcing capability for years, but it’s largely been limited to hard-copy and online help. “True” single sourcing might require supporting multiple mobile device formats, for example, or hard-copy plus multiple online outputs targeted to multiple audiences. Few authors need this level of flexibility yet, but market changes will eventually make it necessary. Such single sourcing will call for tools that offer variables, reusable chunks of content, conditionality, selectable CSS chunks, and so on. The price will be a need for rigorous planning and enforcement of standards new to many authors.

Effects?  Further increases in complexity, a further need for rigor and standardization, and shorter turnaround times. For non-techie authors who survived the shift to HTML, XML may be the last straw.

The Mistakes and the Response

This history has seen several consistent mistakes, the primary ones being: 

• Continued hand-coding. In the past, authors hand-coded because they had to due to HAT limitations. Today, most HATs are good enough that authors now hand-code because they want to. Fewer and fewer do, but it’s still common.
   
• No authoring standards. In the past, projects and development teams were small enough, lead time long enough, technical requirements simple enough, and user expectations low enough that inconsistent authoring wasn’t a major problem. That’s changing today.
   
• Not knowing how to use your HAT. Many HAT users have never been formally trained in the mechanical, design, or management aspects of their HAT. They were just told to “go learn it”. A surprising number of users have down just that. They’re working inefficiently but they are working. But many untrained HAT users are just struggling, producing hard-to-manage output, and just feeling out of control.

In my opinion, here’s what needs to happen to fix these mistakes and get the power and flexibility to make full, effective use of the tools.

• Define a formal policy to ban hand-coding in all but exceptional cases. There will be cases where a HAT can’t perform some task, but those cases will become rarer as HATs get better. Today’s authors should understand the codes and concepts in order to understand what their HAT is doing, but the authors should rarely if ever find themselves actually typing codes.
   
• Define, promulgate, and enforce standards in technical areas like style sheets and templates. The result will be a more disciplined development culture that creates more consistently coded, structured, and formatted content. Another benefit will be greater development speed as the style sheets and templates automate decisions that authors once had to mull over.
   
• Define, promulgate, and enforce standards for development best practices across the documentation group or even across the company. The result will be a more effective development culture that efficiently captures and shares the experience, skill, and contributions of all the developers.
   
• Budget to train authors on how to use their HAT and any supporting technologies. Not doing so – just buying a HAT and telling authors to “go learn it” – may save money in the short-run but is tremendously wasteful beyond that.

The beauty of XML is that it offers tremendous power and flexibility, but only if we use the tools properly in the first place. A character in one of the Spiderman movies put it nicely—“With great power comes great responsibility.”

About the Author

Neil has 27 years experience in technical communication, with 21 in training, consulting, and development for various types of online formats and tools such as WinHelp, HTML Help, CE Help, JavaHelp, RoboHelp, and some now forgotten. Neil is a columnist and frequent speaker for the STC and other professional groups, a senior member of the STC’s Boston chapter, the creator and manager of the Beyond the Bleeding Edge stem at the STC’s annual conference, and an Associate Fellow of the STC.

Neil is a Madcap Certified Instructor for Flare, and a Macromedia-Certified Instructor for RoboHelp and Captivate. He provides training, consulting, and development for online help and documentation, Flare, RoboHelp, Captivate, XML, and single-sourcing through Hyper/Word Services of Tewksbury, MA. He can be reached at nperlin@concentric.net, www.hyperword.com.