Why formatting matters

Well, with the growing importance of single-sourcing (publishing the same content in various output formats) and reuse (reusing bits and pieces from one document in another one), WYSIWYG has lost a lot of its glamour. And while structured authoring is taking up an increasingly central role in the world of technical documentation, it is the turn of the WYSIWYG tools to appear old-fashioned.

The new kid in town is called XML and pure XML editing environments can count on more public interest than their SGML or HTML ancestors ever had. But is pure XML really better than WYSIWYG? Why are leading XML tools including sneak previews of possible outputs? Is there another paradigm that combines the virtues of true XML with the comfort of WYSIWIG?

In the beginning was the word (and not much else)

Before the era of desktop publishing, when most people were using word editors running on DOS or UNIX, formatting was called typesetting and done by specialists in printing companies. In those days, authors were true writers, producers of content, unburdened with the task of making their output look good in print. That was someone else’s job and responsibility. The author was only responsible for correctness and completeness of the content.

With the absence of formats, authors had to annotate their plain text with instructions for the professional typesetters: make this heading larger, add bullet points to these sentences, etc. And in many cases, the typesetter could more or less determine how large the headings would become and which particular bullet character to use. Authors created content, typesetters were in charge of formatting.

Even after Windows had conquered the workplace and digital printers allowed the job of physical typesetting to turn into computer-aided formatting, this formatting job was largely left to professionals with special page layout programs that often ran on Macs.

I still remember being the only employee with a Mac in a German high-tech computer company, gathering input from all departments and processing it overnight into a 150-page manual for a supercomputer that was never built in the end. The only way to get that job done before time ran out was to remove all formatting from whatever input I received and rigorously reapplying format tags. If only I would have had XML input, an editor with XSLT capabilities and a decent publishing engine – I would have had at least a couple of hours of sleep that night. But I am jumping ahead of myself here, so let’s take one step back.

The woes of WYSIWYG

With the introduction of cheaper, easier to use desktop publishing software, creating formatted content entered everyone’s reach. Gradually, more and more sophisticated formatting capabilities were implemented in common editors such as Microsoft Word. With the claim that output on the screen would exactly match what your printer would eventually produce on paper, authors started to be more concerned with the output, trying to make the formatting match their personal preferences.

With formatting in everybody’s hands and no formal training for most of them, a plethora of personal styles emerged. Some were nicely structured, using named styles and no overrides, but most were simply entered ad hoc, using the formatting buttons that were easiest to get at: underline, bold, italic and font sizes. I have seen lengthy documents consisting entirely of “Normal” style with 1000s of overrides for individual paragraphs, sentences, words or even single characters. In such documents, changing the house style – or even applying it for the first time – becomes a nightmare.

WYSIWYG promised to bring the capabilities of true publishing to everyone’s desktop, but it did not tell people about the hidden dragons and crouching tigers that came along with this paradigm. Content and formatting became completely mixed in one single authoring environment. And with increasing numbers of formatting features that were added to each new version of every text editor came new levels of dependency between the pure content and the way in which it was being rendered.

Figure 1: Formatting options take up all the toolbar space in Word.

The problem got worse when the exact same source started to be used for various output formats: not just print but also CHM, WebHelp and eventually a range of outputs for PDAs, mobile phones and tablet computers. By now, single-sourcing seemed a good idea, but not if you wanted to keep formatting under control in the way you were taught by WYSIWYG editors. With single-sourcing, the promise of WYSIWYG has been broken for most outputs. Yes, you can make your content look good for one output format, but if you want to reuse the same content for a totally different format, you might get completely useless results. And even if it looks good in your browser, a user might increase the font size in his browser and ruin your carefully crafted HTML screen design. Maybe the qualifier “In Print” should be added to the acronym, making it WYSIWYGIP.

A new kid in technical authoring town

With the call for single-sourcing came the need for different output formats, and the single most important output format of the era was HTML. While some online Help authoring environments built on Word (keeping the customer base in their comfort zone as much as possible), which was then transformed into HTML, other products like RoboHelp turned HTML into the work environment of the author (from which content could be exported to Word if required). With this approach, applying different style sheets to the same content in different single-source layouts allowed separating content from formatting to a certain extent. But still, the HTML tags were largely defined as formatting tags, much the same as the paragraph and character styles applied in a Word or FrameMaker document.

And then XML rode into town. Suddenly the separation between content and formatting became a lot more profound, as the tags were no longer connected to the formatting in an immediate manner. Semantic tags introduced an extra layer between the content and the formatting in which the content was going to be rendered. In the DITA 1.2 standard for instance, naming a topic a <task> or a <concept> might or might not cause differences in the format applied to the <title> child element. The differences in formatting might even depend on the output that is selected: Kindles do not offer as wide a variety of formatting options as PDF, but tablets offer much more.

Putting semantic labels into files to define the meaning of each content item and its position in the underlying structure of the document was the single most important change in technical documentation since the introduction of personal computers for this type of work. All of a sudden, intelligent software can retrieve information from XML documents based on meaningful semantic labels. You can tell a piece of software to get the <supplies> list from a <task> and send it to the <warehouse employee> who prepares the supplies packages for the <maintenance engineers>. If all of this information is available and marked up with semantic labels in the technical documentation, the software can find and process it. In a similar manner, the Bill Of Materials for a machine can be processed into a spare parts catalogue without any human intervention.

XML offered one more great advantage over other editing environments: as an author creating XML content, you were not dependent on one specific authoring tool anymore. Any text editor could be used, as the semantic labels are themselves expressed in the same text as the content, using angular brackets to distinguish them from that content. XML is not just Xtensible, it is also Xchangeable.

Pure XML and the author’s performance

Of course, someone – the technical author – has to put the formatting information in the content in the first place. And using semantic labels to mark up content instead of applying the usual and other formatting tags did change the requirements for editing tools. Tags had to become visible for the technical authors to see which semantics they were applying.

In pure XML editors, tags are shown as tags and all text formatting is removed. It is possible to have the tags shown in red and attributes in blue, just to make the metadata stand out from the content. The fact that most XML editors include that option signals that there might be something wrong with the notion that pure XML editing is what makes authors most effective in creating good content.

Figure 2: SyncRO Soft’s oXygen editor showing a DITA task in XML view

True, authors are no longer tempted to tweak their content so that it will fit on the page or match their personal formatting preferences. But how are authors supposed to see whether the structure in the content is really the structure they mean to express? If you have a long file with steps and lists and nested lists, how do the tags help you in finding out that a particular item has been nested one level too deep? And if you are new to structured editing and XML, how are you going to survive this all-new paradigm in which you have to choose a tag out of a lengthy catalog of available ones and create previews of output to see if this is really what you meant to do?

WYSIWYM is the answer

In fact, while creating their content, authors are readers, too. When they are creating content with a certain structure, they have to check both the content and the structure for correctness. Leaving it up to them to read and interpret the tags and visualize the intended output in their minds puts a lot of burden on them and introduces a human error factor that is unnecessary.

After all, the structure of a document must be expressed in some formatting, otherwise readers of the final output will not be able to figure out what that structure is. Not all details need to be visible, but at least some visible cues are required for the output to be readable at all. And some formatting, even though it is not strictly required, is so helpful that it would be a waste not to use it. A element in a topic may receive an icon of a hammer and screwdriver to indicate it is a task. The same element in a <concept> may receive an icon of a light bulb. Structure is expressed via formatting elements and if the formatting elements are defined effectively, readers quickly understand the structure of the content and immediately know where to find the information they are looking for.

The market for technical authoring environments has proven the point that authors need to see at least some formatting while creating content. Most or all of the leading XML editing environments have added this type of support. In several cases, this user interface is called Author View. In this type of view, the XML document does not look like XML at all. Rather, it looks like a Word or FrameMaker document with the page boundaries and all other page elements (headers, footers, page numbers) removed. These types of user interfaces are known as WYSIWYM: What You See Is What You Mean.

Often, the Author View is combined with some kind of structure overview in a separate window or panel of the user interface. SyncRO Soft’s Oxygen offers an outline view plus elements catalog and adds a breadcrumb trail in the menu bar to show you where you are in the structure of your document. But the toolbars, context menus and optional additional panels would still puzzle or even scare away a lot of XML-newbies.

In the new release of FrameMaker, the well-known WYSIWYG interface (for printed documents, of course) is now accompanied by both a pure XML view and an Author View. Here, the WYSIWYM author view is truly basic in offering only what the structured author really needs: a structure view for easy navigation plus an authoring window that shows placeholders, context menus and an elements catalog for inserting elements and only those toolbars that an author should ever need to create structured content.

Figure 3: FrameMaker 11 showing a DITA document in the new Author View.

The instant preview in WYSIWYM comes without the false promise of WYSIWYG. It is intended as a rough preview, just good enough to check whether the structure is correct and allow you to concentrate on the content while creating it. It has the best of both worlds: the separation between content and formatting that pure XML offers plus the comfort and luxury of the editors that we are familiar with. It removes the nerd look and feel of true XML, as well as WYSIWYG’s temptation to tweak the content so that it fits better on the page. There is no page, there are no formatting controls. There is just content, and visible – not visualizable – structure.