If you let one of your houseplants completely dry out and then try to bring it back to life by dumping a large amount of water in the pot, you will end up with water all over the floor. Dry soil cannot absorb moisture quickly so the water you pour in will run through the soil, out the hole in the bottom of the pot, into the saucer the pot is resting on, over the sides, and onto the floor. Damp soil can absorb moisture far more quickly that dry soil. Readers are like that too. Experts can absorb much more information much faster than novices. Thus experts read far more than novices do.
Is Single-Sourcing Dead?
Neil Perlin poses the question (and answers in the negative) in a response to my post “Time to Move to Multisourcing“. Perlin raises a number of points that deserve discussion. But first, a little clarification is needed.
The term “single sourcing” is used to mean a number of different things in tech comm and content strategy. Among them:
- Producing PDF and Web pages (or help) from the same source file or files.
- Content reuse (in other words, storing a single source for a piece of information and publishing it in various places).
- Using a single repository/file format for all content.
These three things are independent of each other, though they may well be used together. For instance, you can produce PDF and help from the same source files stored locally on different workstations running different software, and you can use a single repository and file format without reusing content or outputting to more than one format (as many people using a Web CMS or Wiki do).
Is personalized content unethical?
Personalized content has been the goal of many in the technical communication and content strategy communities for a long time now. And we encounter personalized content every day. Google “purple left handed widgets” and you will see ads for purple left handed widgets all over the web for months afterward. Visit Amazon and every page you see will push products based on your previous purchases. Visit Facebook …
Well, and there’s the rub, as Mark Zuckerberg is summoned before congress for a good and thorough roasting. Because what Cambridge Analytica did was personalized content, pure and simple, and no one is happy about it.
Time to move to multi-sourcing
Single sourcing has been the watchword of technical communication for the last several decades. We have never fully made it work. A pair of seminal posts by prominent members of the community give me cause to hope that we may be ready to move past it.
Single sourcing is about the relationship between sources and outputs of content. Traditional publishing methods had a one to one relationship between sources and outputs, where each output was generated from a single source.
The inefficiencies of this model are evident, particularly where different outputs are just different formats of the same document, such as PDF and HTML. Single sourcing attempts to remove this inefficiency by combining content into a single source:
As Sarah O’Keefe comments in Single-sourcing is dead. Long live shared pipes!, the first of the two seminal post I want to discuss:
[W]e have been trying for a world in which all authors work in a single environment (such as DITA XML, the Darwin Information Typing Architecture), and we pushed their content through the same workflow to generate output. We have oceans of posts on “how to get more people into XML” or “how to work with part-time contributors.” The premise is that we have to somehow shift everyone into the One True Workflow.
But there are two problems with this model. The first is that the source in this model is significantly more complicated than the individual sources in the original model. The added complexity comes from the need to support all of the potential outputs from a single source format and all of the management operations you want to perform on that content. But that complexity is imposed on everyone who writes any of the sources involved. Where people used to be able to write in Word or a simple visual HTML editor, they now have to write in Flare or DocBook or DITA or a complex CMS interface.
You can’t get everyone to agree that taking on this additional complexity is worth their while, and in practice it often slows down getting particular pieces of work done (even if it improves efficiency overall). So what happens is that some people drop out of the system, or refuse to sign on for it in the first place, or don’t use it for everything they do, leaving you with something that looks like this:
Life remains just as complex for the folks who continue to use the system, but the organization realizes fewer benefits from it because not everyone is using it.
Modern content demands have only made this situation worse. We now look to do more than simply issue content in multiple formats. We want to select and combine content to create different outputs for different audiences. We want to enhance content with metadata for consumptions by intelligent downstream systems. We want to richly link and organize content both statically and dynamically. We want to control terminology, manage quality, and steamline localization. All of this leads to greater complexity in your source format in order to support all of these things:
This added complexity is only going to result in more defections and dealing with the complexity, not to mention paying for the complex system, is only going to compromise your hoped-for ROI.
Is there another way?
O’Keefe suggests that the answer may lie in what she calls “shared pipes”. That is, a system in which content flows from many sources through a shared publication system and out to many different outputs.
This is a diagram I have been drawing for many years, and I love Sarah’s shared pipes analogy to describe it. It comes down to this:
There are many sources of content and many outputs, but the source material goes through a shared process in the middle that handles multiple outputs, selecting and composing for multiple audiences, adding rich metadata, rich static and dynamic linking, and all the rest.
But wait, don’t all those separate sources constitute that great boogeyman of the content industry, silos? Yes, they absolutely do, and that brings me to the second seminal post, Don’t Dismantle Data Silos, Build Bridges by Alan Porter. Porter begins by noting the reluctance of people to throw out their current way of doing things in favor of the one great single sourcing system:
Let’s face it: no one is going to throw out their incumbent systems just because we say they should. Especially not if those systems are still doing the job they were purchased to do. We have all worked with systems that are “good enough” to fulfill a specific set of tasks.
Removing and replacing existing systems isn’t quick or cheap, but the biggest hurdle isn’t budget, or technology (although that’s what’s often cited) — it’s human.
The human element is indeed crucial. Technically, the single sourcing model might work very well if it didn’t have to be used by humans. But, as Porter notes, humans build systems to suite their own work and they are not willing to give them up to make someone else’s work easier.
Nor should they, since the quality of a person’s work very much depends on the suitability of their tools to the task at hand. You don’t do your best brain surgery with tools designed for trimming hedges. The current systems that people are using may not be the best possible system they could be using, but at least those systems are specific to the work they are doing. They are comfortable. Perhaps we could design them a system that is even more comfortable, but if so it will be a system more specific to their task, not a single gigantic complex system designed to be a single source of everything.
So, a multi-source system lets us keep each source system focussed on the needs of the individuals who contribute to it. We then collect information from all those systems and run them through a shared publication process to produce whatever outputs we need. As Porter says:
Each customer interfacing system can still stand alone and address the needs of a particular line of business, or be an enterprise single source of truth. Yet by passing data between them, or existing enterprise business systems, they can be the foundation of a fully connected continuous customer experience.
Of course, it is not quite so easy as that. Setting aside the technical issues of actually connecting the various systems together, we are still left with the issue of whether the content coming from each of these systems has enough structure and metadata attached to it for the shared pipes to actually perform all the operations we need them to perform.
As O’Keefe points out, you don’t actually need every source to contain the structures to perform every system function:
not all content needs the same level of quality review. Instead, we’ll have make a distinction between “quick and dirty but good enough” and “must be the best quality we can manage.”
Thus it might be perfectly fine for some of your content to be written in a simple format like MarkDown and pass through your shared formatting pipe without necessarily passing through every other function and process of your central system.
But what about the content that does need to pass through those functions. Can we support this without making every individual silo format as complex as our single source format:
Clearly if the silo formats have to be as complex as the single source format, we have accomplished very little. Even if each of these super-complex formats is specific to its silo, it is not likely to be supported by the existing system, nor is it likely to be comfortable for the individual contributor.
How then do we keep the formats of the individual silos small while still supporting all of the functions of the central publishing system for all the types of content that need it?
The answer lies in structured writing, particularly in the style of structured writing that I call “subject domain.” In subject-domain structured writing, the markup you add to the text is specific to the subject matter. Here, for example, is a recipe in subject-domain a structured writing format:
recipe: Hard-Boiled Egg introduction: A hard-boiled {egg}(food) is simple and nutritious. ingredients:: ingredient, quantity, unit eggs, 12, each water, 2, qt preparation: 1. Place eggs in (pan){utensil} and cover with water. 2. {Bring water to a boil}(task). 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
The incomplete bridge
In the Top Gear Patagonia Special, the presenters come upon an incomplete bridge and have to construct a ramp to get their cars across. This is a great metaphor for technical communication, and, indeed, communication of all kinds: the incomplete bridge.
Technical communication is often described as a bridge between the expert and the user. But that bridge is always incomplete. The user always has to build the final span that connects the bridge to the bit of ground they are standing on.
This is true for several reasons, the most basic of which is that you have to contextualize any information you receive to your own project in order to act on it confidently and successfully. If the document tells you to push the red button, it is still your job to determine if you are looking at the right device and the right red button, and if your purpose will truly be served by pressing the red button at this time. The document can never entirely ensure that you do not press the wrong button on the wrong device or at the wrong time for the wrong purpose. Only the individual reader can determine those things, and thus only the reader can build the final span of the bridge.
Structured Writing and Free Trade
In my last post, I promised I would reveal the unifying idea that I developed for my new book on Structured Writing. This is the post. So what does it have to do with free trade? Mostly it is that I see the same pattern in discussions of free trade that I do in many discussion of structured writing: a failure to focus on the big picture.
Free trade has been pretty much a given for the last several decades with nations and trading blocks negotiating ever freer trade. But of late the virtues of free trade have been called into questions by the Trump/Sanders wing of American politics, which has those of us in Canada, for whom America is our largest trading partner, a little anxious.
In Praise of Long-form Content
Yesterday I wrapped up work on my new book on Structured Writing and delivered it to the publisher. There will be more work to do, of course, after the pre-publication review process is complete, but in a broad sense, the book is done. That is, the arc of the book is complete.
Good books have an arc. Finding that arc is one of the great joys of long-form writing. Of course, this blog is about short form writing — about Every Page is Page One topics that serve a single discrete purpose for the reader. But in a sense even a book should fit that mold — should serve a single discrete purpose for the reader. The whole should be more than the sum of the parts. There should be an arc, something the book says that is more than an accumulation of details, and that allows the reader to see the details in a new light — and to act differently and, hopefully, more successfully, in that new light.
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
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.