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

Designing for Feedback

We were discussing the biggest challenges in Tech Comm at the last STC Toronto brunch and we all seemed to agree that the difficulty getting feedback on the effectiveness of the content we create is the biggest challenge. The things that really matter in technical communication is whether users can achieve their goals after finding and reading the docs, and whether that makes a difference in whether they buy from you again or speak well of you to their friends and colleagues. These things are incredibly difficult to measure. You are just not there to see them happen, and it is very difficult to separate their effects from the effects of the work that designers, developers, sales people, trainers, field engineers, and support staff do. read more

Another demonstration that language is stories

Sam Jackson makes it look easy, but Siri and her cohorts are still pretty dumb. If experience alone does not illustrate this to your satisfaction, a recent article in the MIT Technology Review, Tougher Turing Test Exposes Chatbots’ Stupidity, shows just how low their success rate is in understanding real language.

The Winograd Schema Challenge asks computers to make sense of sentences that are ambiguous but usually simple for humans to parse. Disambiguating Winograd Schema sentences requires some common-sense understanding. In the sentence “The city councilmen refused the demonstrators a permit because they feared violence,” it is logically unclear who the word “they” refers to, although humans understand because of the broader context. read more

Affordances are relative

Affordances, those features of a product that help you figure out how to use it, are relative.

Most of the busses in the Kitchener-Waterloo region have rear doors that open when you wave your hand in front of them. The one I took downtown this morning must have been an older model because it just had two vertical push bars on the doors.

When we arrived at the terminal, the young woman at the front of the queue to get off started to wave her hands in front of the door, which did not respond. Puzzled and alarmed, she began to shout at the driver to open the doors, until someone behind her said, “push the handle”. read more

Why we need constrainable lightweight markup languages

This post is in response to a Twitter conversation that started with:

This led to a discussion about extensibility and constraints in markup languages. Markdown is a pretty simple lightweight markup language (and popular for that reason) but it is what it is. You can’t add anything to it except by creating your own variant by modifying its code (which lots of people have done). read more

Can Content be Engineered; Can Writers be Certified?

tl;dr: We can apply engineering methods to content development, but we do not have the body of proven algorithms or known-good data to justify formal certification of communication professionals they way we have for doctors and engineers.

We talk about content engineering. I call myself a content engineer sometimes. But can content really be engineered? Is content engineering engineering in the same way that engineering a bridge is engineering, or only engineering by analogy?

This post is prompted by a fascinating conversation with Rob Hanna and others at the monthly STC Toronto Networking Lunch. The conversation morphed into something I think I can fairly characterize as: is there a uniform methodology to technical communication, one that can form the basis of a curriculum, a certification, or a toolset, or is there a legitimate diversity of approaches, roles, methods, and tools. read more

Writing Excellence Through Domain Awareness

A little while back, Tom Johnson posted an article entitled Seeing things from the perspective of a learner in which he says, “The balance between knowing and not knowing is the tension that undergirds the whole profession of technical writing.”.

I think that is absolutely correct. The point, after all, is to assist the reader on their journey from ignorance to knowledge. I say assist, because this is not a journey that can be accomplished simply be reading. The reader has work to do to integrate their knowledge. They need to get their hands dirty. But a sympathy with the troubles and perils of that path is at very least, highly useful to the writer. read more

What is an “Expert Writer”?

“Hire Expert Writers,” Says Google

That is the title of a post from M2Bespoke about Google’s emphasis on returning reputable content. What is an “expert writer” in this context?

Many of those who have commented on it and passed it around take it to mean expertise in writing. That seems to be the interpretation that the author of the article is making as well:

There’s no doubt you’re experts in your industry, but do you have professional writers within your business to convey that expertise? Google says: if not, why not? read more

Why does XML suck?

XML sucks. Don’t get me wrong. All kinds of really valuable and important systems use XML to perform vital functions. But performing a vital function does not keep something from sucking. Lots of people think Windows sucks, but it performs a vital function, and lots of people use it because of that. In fact, performing a vital function is what keeps sucky things around. If they perform a vital function, they are hard to get rid of, despite the fact that they suck.

Not that that prevents people from trying to work around them. read more

One Answer, Many Questions

It is often appealing to think of technical communication as a process of answering user’s questions. The difficulty with this view is that one answer can have many questions. If you answer each of those questions, you would be providing substantially the same answer over and over again.

This is very easy to see on StackOverflow, a question and answer site for programmers. Privileged user of StackOverflow can mark a question as a duplicate of another question. Here’s an example:

A question marked duplicate on StackOverflow.

The question here is “How to check if a variable is a dictionary in python”. This is a question that programmers are going to ask themselves many times. It is a specific instance of a more general question, which is, “how do you check if a variable is of a specific type in Python?” read more