Search results

Review of Alan Porter's Wiki: Grow Your Own for Fun and Profit

by Tom Johnson on Nov 25, 2010
categories: book-reviews technical-writingwikis

Wiki: Grow your Own for Fun and Profit, by Alan Porter
Wiki: Grow your Own for Fun and Profit, by Alan Porter

Alan Porter's Wiki: Grow Your Own for Fun and Profit, published by XML Press in October 2010, provides an excellent introduction to wikis. This is a short, easy-to-read book spanning about 150 pages. Alan has a keen sense of organization and liveliness in his writing. He carries the gardening metaphor throughout the book, ending with five solid case studies and an extended response to common criticisms against wikis.

Sometimes discussions about wikis make it seem as if they're a new technology. But Alan explains that Ward Cunningham developed the first wiki in 1995 -- fifteen years ago! Despite the relative ease with which Alan responds to wiki concerns (about inaccuracies, lack of participation, disorganization, and so on), wikis still haven't gained traction as the predominant authoring platform.

One has to wonder, given the many advantages of wikis, why they haven't they taken off as the platform for web and help content? Especially in an age of collaborative authoring, distributed ownership, dynamic editing, and agile development, you'd think wikis would be the most common platform for help authoring in tech comm departments.

And yet, in the 2010 WritersUA Tools Survey, wikis aren't even included as a tool (see the survey's list of tools). Almost every other help authoring, graphics, and video, and layout tool is mentioned, but wikis are absent. Either WritersUA accidentally omitted them (this year and every previous year), or they don't take wikis seriously, or wikis aren't considered help authoring tools.

My point is that wikis still have a long way to go toward mainstream adoption, despite their decade-and-a-half presence on the web. Alan's book is a welcome addition to the promotion of wikis and wiki culture.

Although Alan's audience seems more focused on new wiki users, he does dive into an issue that I struggle with: wiki round tripping. With round tripping, you publish from a source format to a wiki format, allow the wiki to be updated, and then write your updated wiki content back to your source format. For example, with WebWorks, Alan says the original documentation source is in Framemaker, which they publish to a wiki format using ePublisher. If they did round-tripping, after the wiki was updated, they would write the updated wiki content back to Framemaker.

However, WebWorks doesn't do round tripping. After users make edits to the WebWorks documentation, the WebWorks team manually updates the source Framemaker files with the changed content.

Even if they wanted to do round-tripping, it isn't easy to achieve technically. And I assume the technical solution isn't available because apparently there isn't a business case for it.  Alan says,

When I hear people using the phrase 'round-tripping' they tend to be talking in terms of automating the process. When I have asked people what the business case is for implementing automated round-tripping, very few have an answer beyond "well it would be cool.

Alan notes that with a multilingual wiki, there may be a valid business case. But for most corporate content, round-tripping may pose liability or legal issues, and requires human intervention to evaluate whether the updated wiki content should change the source file. If round tripping is necessary, Alan recommends making the wiki the original source.

This section was most relevant to me for several reasons. First, round-tripping is very much a tech comm topic rather than a general wiki topic. Second, Alan gets into a difficult issue and explores it in depth. And third, there is no easy answer.

In the authoring process for some of my projects, we do keep the wiki as the original source, rather than maintaining a separate source of content. We all collaborate through the wiki, building the documentation as we go. In my opinion, working in Framemaker and then publishing to the wiki (the WebWorks model) undercuts the collaborative nature and power of wikis. If you're the only one creating the documentation, it might make sense. But in a collaborative authoring model, with a team of internal and external authors, why create documentation in Framemaker first and then publish it to the wiki? How exactly would you share the content? Also, if community momentum picks up, how can you feasibly input the community's constant updates back into the source files?

However, if you do use a wiki as the original source, you run into a problem: how do you selectively package up the wiki content and output its content into printable formats? How do you personalize the topics based on specific roles?

These latter questions might be related more to the wiki tool rather than wikis in general. Some wikis allow you to bundle the content together as a PDF output, while other platforms require extensions and hacks to achieve this. Access control also varies widely among wikis. Confluence offers different access control levels, while Mediawiki has an everything-open or everything-closed policy.

Alan's book makes me reflect more about wikis. Will they ever take off? What holds them back? Is it the lack of a universal wiki syntax? Is it because wikis all too often devolve into chaos? Is it because the fundamental idea of volunteer group writing is flawed? I'm not sure. I prefer wikis more than traditional help authoring tools, but wikis still pose many challenges. I'm glad Alan took the time to write a book on wikis. It will help push tech comm authoring models more toward wikis.

For a sample chapter and links to buy Wiki: Grow Your Own for Fun and Profit, see the XML Press site book page. To read Alan Porter's blog, The Content Pool, go to http://4jsgroup.blogspot.com.

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.