Publishing Perspectives: Wikis, Structure, and Publishing

For the last couple of years, we have been doing something that is rare among publishers. We have been developing books using both a wiki and XML-based structured writing. On the surface, these two technologies represent opposite ends of the writing spectrum. Wikis are mostly associated with casual, collaborative projects and bottom-up design (assuming there's any design at all), while structured writing is associated with carefully planned, tightly managed projects and top-down design.

Despite those differences, we have been able to use these two technologies together effectively. The key has been to take a realistic approach to how much structure we need and how much collaboration we need (and when we need it). We've also taken advantage of some tools that have significantly improved our ability to make these two approaches work well together. While we've done this in the context of publishing, I think there are parallels in technical communication that are worth highlighting.

Why structure?

Structured methodologies are great at addressing production efficiency issues. You can target multiple output media from the same source, you can adjust your output without changing the source, you can reuse content in different contexts, and you can break the connection between content and presentation, relieving writers from the need to deal with presentation issues. While you can debate whether actual writing productivity (that is, output per unit of time) is improved significantly (if at all), there is little doubt that in many tech comm environments appropriate application of structured writing can yield overall productivity benefits when you consider writing and production together.

Our experience as a publisher confirms that. The amount of time and expense it takes for my company to handle back-end production for unstructured content (e.g., Word), is significantly greater than what it takes to handle structured content. The difference can be anywhere from 25% greater, for a book that is primarily undifferentiated text, to 100% or more, for a book that has a significant number of tables, notes, sidebars, figures, etc. or a lot of inline markup. Therefore, there is a big benefit to us if we can get structured content as early as possible in the development cycle.

The challenge for a publisher is that we don't have the leverage over our authors that an employer has. We don't have the luxury of training authors to use our systems nor can we pick projects only from authors who have structured writing skills. Instead, we decide whether or not to publish a book based on the value of the topic and the ability of the author to contribute something significant. We need to find the easiest way possible to capture and use content from any author, regardless of his or her level of skill with structured writing and tools.

Enter wikis

Wikis give us a way to approach this dilemma. Wikis are, in many ways, the mirror image of structured writing. They provide easy authoring and easy collaboration, but I have yet to find a wiki that supports structured content as its native format. Wikis largely solve the authoring problem and give us a way to bring in collaborators (we have had editors, indexers, illustrators, foreword writers, and reviewers) who can directly access and edit books under development. But they take us out of the structured world.

The ideal would be to have an authoring interface that is as easy to use as a wiki combined with XML structure under the hood. That way, you could realize the benefits of both technologies.

Putting it together

Despite the challenges, we have been using wiki-based development for several years, starting with Alan Porter's WIKI, which was written, edited, and indexed in a wiki, then exported and converted (through a multi-step process) to DocBook for production. While that process was held together with paper clips and rubber bands, it worked, and we used it for two more books.

When we published Sarah Maddox's Confluence, Techcomm, Chocolate, we used Confluence (of course) and the Scroll DocBook Exporter from K15t Software, which allows us to directly export DocBook from Confluence.

The engineers at K15t are hosting a Confluence instance with the exporter for a new series of books that has dozens of contributors working in the wiki. This should provide us with a realistic test of whether the basic concept scales. (Disclosure: K15t is giving us complementary access to their wiki, and in return, we will track our progress on our website and give them feedback.)

We already know that for our purposes, which do not require writers to use any of the less-traveled nooks and crannies of DocBook, the combination is working well. Whether this approach will work in a corporate technical communication group is debatable. I believe that wikis provide a great way to collect input from subject matter experts and other infrequent contributors, and I know it has worked well with professional writers working on our books. However, whether a wiki is better than a dedicated editing tool for writers who work with structured content every day is much less clear, and I'm inclined to think that this group of writers would be better off with a dedicated tool (though it would be great if that dedicated tool could be integrated into a wiki environment, giving you the best of both worlds).

Please add a comment if you have had success (or not) with wikis as a structured authoring environment.

Richard L. Hamilton is the founder of XML Press, which is dedicated to producing high quality, practical publications for technical communicators, managers, content strategists, and marketers and the engineers who support their work. Richard is the author of Managing Writers: A Real-World Guide to Managing Technical Documentation, and editor of the 2nd edition of Norm Walsh's DocBook: The Definitive Guide, published in collaboration with O'Reilly Media.