DocBook resurgent: what it tells us about structured writing and component content management

A new XML-based content management system that is not based on DITA. Bet you didn’t see that coming. But I think it tells us something interesting about the two sides of structured writing.

Tom Johnson’s recent sponsored post explains the origins of Paligo, a relatively new CCMS out of Sweden. Paligo was developed by a company that had formerly been a DITA consulting shop in an attempt to come up with something that was easier to use (and less expensive) than the DITA solutions they were implementing.

What is interesting to me about Paligo is that they chose DocBook rather than DITA as the underlying XML vocabulary. Why? Quoting Tom:

And it turns out that building on a foundation of Docbook XML is considerably easier than building with DITA. DITA tends to impose more restrictions about what you can and can’t do, Svensson says. Even so, Paligo is only “based on Docbook.” Paligo extends from this foundation, adding what they need and not letting the content model restrict the system, while maintaining full capability to export to the open standard.

This is interesting because DocBook is a large and complex specification. (I want to say larger and more complex than DITA, but I’m not sure if that is true anymore.) Why use it as the basis for what is supposed to be a system that is easier to use than DITA?

The answer seem to be lack of restriction. DocBook may be as large and as complex as DITA, if not more so, but it is much less restrictive. DITA has lots of restrictions on what you can and cannot do in each topic type. DocBook has very few. You can combine DocBook elements in just about any way that might occur to you. And apparently Paligo loosens DocBook even further.

Why is this significant? In a CCMS (Component Content Management System) the whole point of the system is to let you assemble documents out of pieces. The main benefit of this is content reuse. The main problem standing in the way is composability: the ability to put pieces together and have them work.

Composability is an interesting problem. Lego sets and Mechano both have composability within their own systems, but there is little composability between Lego and Mechano.  You cannot freely exchange the bits. Composability is similarly a problem between the many different file types used across a typical enterprise. If you want to practice component content management on an enterprise scale, you need a composable format across the enterprise.

There are two ways to get this. One is to allow each group in the enterprise to have their own format, but insist that it must be transparently convertible into a common composable format. The other is to get everyone to use the common composable format directly. The latter sounds easier, so that is what most people choose. (It is not always easier, but people only find that out later.)

To get everyone in the enterprise using a single composable format, you need it to be easy to use, as well as being flexible enough to serve everyone’s needs. What to choose?

DITA has been the default choice for a while now, but the problem is that DITA is not really easy to use. Several companies have tried to make DITA easier to use. (Tom mentions EasyDITA in his article.) But DITA comes with restrictions and restrictions are hard to learn and annoying to comply with unless you really understand the point of them.

Lightweight markup languages such as Markdown and ReStructuredtext have become popular as well, with various CMS and publishing systems being built around them. But while they are simple and easy to use, their simplicity can be limiting. There are things that occur in complex publications that they cannot easily represent.

DocBook offers a far richer set of markup structures that can represent all of these things, but without the restrictiveness of DITA. It makes sense, therefore, for a company like Paligo to choose it for their underlying document structure.

There is a rub here though, and it has to do with the two sides of Structured Writing that I mentioned at the beginning. Those two sides are composability  and constraint. I am writing a book about structured writing (currently being serialized on TechWhirl) . That book focuses on the constraint side of structured writing.

The constraint side of structured writing is about expressing and enforcing constraints on content. It is about limiting and shaping what is written to meet a particular need. For example, it may constrain a recipe to follow a particular format and include particular pieces of information.

Here is a constrained version of a recipe:

recipe: Hard Boiled Egg introduction: A hard boiled egg is simple and nutritious. ingredients:: ingredient, quantity eggs, 12 water, 2qt preparation: 1. Place eggs in pan and cover with water. 2. Bring water to a boil. 3. Remove from heat and cover for 12 minutes. 4. Place eggs in cold water to stop cooking. 5. Peel and serve. prep-time: 15 minutes serves: 6 wine-match: champagne and orange juice beverage-match: orange juice nutrition: serving: 1 large (50 g) calories: 78 total-fat: 5 g saturated-fat: 0.7 g polyunsaturated-fat: 0.7 g monounsaturated-fat: 2 g cholesterol: 186.5 mg sodium: 62 mg potassium: 63 mg total-carbohydrate: 0.6 g dietary-fiber: 0 g sugar: 0.6 g protein: 6 g read more

Changing the “what” in WYSIWYG

The “what” in “what you see is what you get” is not always “formatting”.

Authors need WYSIWYG (What You See is What You Get) displays to work effectively. This is basic ergonomics. If you can’t see the thing you are supposed to be creating, you will have a hard time creating it well.

But while authors always need WYSIWYG displays, the “what” that they need to see is not the same thing in every case. There can be several different values for the “what” in WYSIWYG.

The term WYSIWYG was coined to describe the displays of word processing and desktop publishing programs. In this case, the “what” was the formatting of the printed document. (At the time we were talking strictly about printing on paper. The “what” you saw on screen was the “what” that was going to appear on paper — more or less.)

This was a big step forward, but the step forward was not enabling people to do typesetting with computers. Doing typesetting with computers had been possible for a long time using a language called TeX, which is still used in some places today. But TeX, has never been widely used because while you can specify formatting with great precision in TeX, you can’t see the formatting that you are specifying as you work. You can only see it afterward when you run the file through the TeX program to create formatted output.

Make a mistake in your TeX markup, and your output may be garbled in ways that make it hard to find your error, and finding and fixing errors can be fiddly and tedious. Desktop publishing was a big step forward because it allowed people to see the formatting they were creating as they created it.

But formatting is not always the “what” in WYSIWYG. In Learning Python, Mark Lutz describes the syntax of the of the Python programming language as WYSIWYG.

Python is a WYSIWYG language — what you see is what you get — because the way code looks is the way it runs, regardless of who coded it.

Lutz, Mark (2013-06-12). Learning Python (p. 326). O’Reilly Media. Kindle Edition.

What he means in this case is that with Python, unlike most other programming languages, the indentation of the source code always shows the logical structure of the program. If formatted poorly, the indentation of code in a C or Java program can be completely misleading as to the actual structure of the code. Lutz provides this example:

if (x)
    if (y) 
        statement1; 
else 
    statement2;

Here the formatting of the code makes it appear as if the else statement belong to the first if statement, but it doesn’t. It actually belongs to the second if statement. The structure you see is not the structure you get. In Python, such confusion cannot occur. Lutz’ Python example looks like this:

if x: 
    if y: 
        statement1 
else: 
    statement2

In this case, the else does belong to the first if, as it appears. If it were indented under the second if, like this:

if x: 
    if y: 
        statement1 
    else: 
        statement2

then the else would belong to the second if statement

In Python, the indentation of the source code determines the structure of the program, and thus the logical structure you see in the source is the actual structure you get in the program. Thus Lutz chooses the term WYSIWYG to describe the language. But in this usage of WYSIWYG, the “what” is not formatting, but structure.

In content engineering there are multiple possible “whats” you might want from a WYSIWYG display. Desktop publishing is based on the premise that the author is also the designer, the typesetter, and the prepress person, so the “what” is formatting. We can be more explicit about this by substituting the word “formatting” for the word “what” in the acronym: FYSIFYG (the Formatting You See Is the Formatting You Get). The desktop publishing approach requires a FYSIFYG display.

Before the days of desktop publishing, when authors were only required to worry about the text, and did not have to wear a dozen other hats, they got by with pens or with typewriters. Both these tools had a TYSITYG display: the Text You See Is the Text You Get.

Today, however, the increasing demand for malleable and repurposable content means neither TYSITYG not FYSIFYG will suffice. We need more than just the text, and something other than text plus formatting. We need structure. What we need to create structured content, therefore, is a SYSISUG display: the Structure You See Is the Structure You Get. Creating such a display, alas, has not been easy.

It might seem like a raw XML file is a SYSISUG display, because all the structure is there in the XML tags. Many XML editors that let you switch to a view of the raw XML will call this “the structure view”. The problem is, while the structure is there, it is not in the least easy to view. There is way too much syntactic noise in an XML file for the reader to easily discern the structure it expresses, as this chunk of the DocBook source for my book shows:

<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="chapter.linkrichly"> <title>EPPO Topics Link Richly</title> <indexterm><primary>Weinberger, David</primary><secondary>on linking</secondary> </indexterm> <blockquote> <attribution>David Weinberger, <citetitle pubwork="book">Too big to know</citetitle> <biblioref linkend="TooBigToKnow"/></attribution> <para><indexterm class="startofrange" xml:id="idx.linking-1"><primary>linking</primary></indexterm>Links are the visible manifestation of the author giving up any claim to completeness or even sufficiency; links invite the reader to browse the network in which the work is enmeshed, an acknowledgement that thinking is something that we do together.</para> </blockquote> read more

How to be Edited

The key to survive being edited is not to look at the edits.

There is a lot of advice available on how to edit other people’s work, and how to edit your own, but not much on how to be edited by someone else. Here’s some thoughts on how to make it a relatively less agonizing process. The key is, don’t look at the edits, look at the result.

The agony of being edited

I’m nearing the end of having my book edited. I submitted the “final” manuscript a couple of weeks back, and since then my editor and publisher, Richard Hamilton of XML Press, has been copyediting and feeding the result back to me a chapter at a time. Since one of Richard’s stated aims in the copyedit was to trim back the manuscript significantly, I was prepared to this to be a painful process. read more