Why I Returned to Wikis for Help Authoring

5/23/2012 Update: See a more updated post, When Wikis Succeed and Fail.

Last week I was feeling a bit stretched out about not having enough time to accomplish everything I needed to do. Granted, I gave several webinars to a total of 2,000 people, which was somewhat stressful, but I was more stressed about the fact that the help material I’d created could have been much better if I had only more time to focus on it. And it wasn’t just help for one product, but about ten others as well, simply because I didn’t have the time to provide the detail and attention the documentation needs.

It’s not because I’m lazy. I’ve actually become somewhat of a workaholic, working on weekends, sometimes a little in the evenings. The problem is that there simply aren’t enough technical writing resources for the work we do.

This situation was taxing my patience, and I started to think of the immediate solution: hire more people. I already mentioned that we have one opening. This is just back-filling a position from a writer who left. But we need about half a dozen more writers, in my opinion, to do a good job. I thought about trying to hire interns, or trying to recruit full-time volunteers.

While I thought of these staffing solutions, I also thought of other things I have heard our leaders say. We have to find a way to meet the demands of a growing membership without commensurately staffing up, some said. And another: If you set your goals higher than you can achieve, you will change your methods in a way that allows you to achieve them.

While I liked these ideas, I didn’t have a clear idea of how to move toward them. I was constantly working in crisis mode, trying to cross off the top three items from an ever-growing list of tasks each day.

As if the documentation challenges weren’t enough, I had also taken it upon myself to do marketing for technology products across departments. I fished for tech news information in every corner I could find– forums, RSS feeds, intranet content, email lists — and then worked with volunteer writers and subject matter experts to get the articles written. I greased the approval system, learning how to navigate the large number of checkpoints with skill and prowess.

Despite some successes, I realized I couldn’t move in two directions at once, both playing documentation and marketing roles for so many products. I needed a way to scale without  simply growing our team with more full-time resources.

A Glimpse of the Solution

Just last week, I felt like I caught a glimpse of the solution. I have a group of 60+ volunteer writers eager to help out. (I wrote about the challenges of managing volunteers last week.) In fact, there are hundreds of church members (as well as non-members) out there who are eager to serve and volunteer for LDS Church writing projects (I work for the LDS Church). I hadn’t  leveraged their efforts except for the marketing side of tech, writing articles for the blog about new releases, updates, and other technology topics. I didn’t have them creating documentation because I saw these as separate efforts.

And then it hit me: These aren’t separate efforts. Good documentation about new sites, tools, and resources can be used for marketing efforts. Marketing and documentation don’t need to be separate efforts. I could leverage volunteer enthusiasm for documentation and then pull highlights from the documentation to post as news for the blog.

And what platform would allow 60+ volunteers to contribute writing and editing? The traditional help authoring system we were using didn’t seem adequate. The cost per license and lack of availability outside the firewall made it impractical as a collaborative volunteer platform. About the only platform that works in this situation is a wiki.

Why I Returned to Wikis for Help Authoring

One of my colleagues explained that volunteers could write in Word templates and then send me those templates. I could then import the templates into the help authoring system and generate help material from it. This was a system he had used in the past for internal SMEs who wrote content. While this could work, he acknowledged that the process would be somewhat impractical.

One of the problems is that we don’t have a set of number of official products we document. If you look at this list of categories on LDSTech, our users have questions that span across products, departments, and roles. There are dozens of different topics, sites, tools, resources, applications, processes, methods, issues, and other areas that users have technical questions about. Would I create a new project to publish information about each one? The most feasible platform to accommodate such an information ecosystem is a wiki.

Pros and Cons of Wikis

I have to say that, in general, I really like wikis, especially Mediawiki. Wikis have so many advantages that it’s hard for me to understand the case for traditional help authoring systems when you need a collaborative authoring environment. Here are the main advantages I see with wikis in my authoring situation:

  • Wikis scale infinitely. Mediawiki is actually free, and it supports an infinite number of users. You don’t have to shell out $1,500 per license. People can just log in and start authoring. It scales to support a growing user base.
  • Wikis remove authoring complexity. Some help authoring tools require a lot of tinkering before they make sense to users. In contrast, adding content to a wiki is fairly straightforward. It’s a matter of asterisks and pound signs and equal signs, for the most part. There is some syntax to learn, but it’s nothing prohibitive. This is essential to expand the base of authors.
  • Wikis allow collaborative authoring. When you have multiple people working on the same content, nothing is easier than a wiki to facilitate this collaboration. Mediawiki even allows more than one person to work on the same page at once, and is smart enough to handle simultaneous commits of the same sections.

I mentioned that I’ve tried using wikis before. Some of the reasons I abandoned it previously include the following:

  • Wikis don’t allow you to single source the content.
  • Wikis are poor at translation.
  • Wikis don’t get enough edits from users to justify the platform.

I want to address some of these objections, if only to provide notes for myself.

Although many people don’t realize it, content re-use in Mediawiki works much the same way as it does with help authoring tools. If you put content in a template, you can re-use that template in any other page as much as you want (it’s called transclusion with Mediawiki). You can also embed pages inside of other pages.

What you can’t do is easily push the content to a nicely printed manual or do other multi-channel publishing (at least not with Mediawiki). You could, however, come close by embedding pages in a specific order and then customizing the print CSS stylesheet. But in all the feedback I’ve seen on forums and through email, I have yet to come across a request for a printed manual. I do often create one-page quick reference guides that people can print. These seem to satisfy the need for a print experience of documentation.

With translation, while help authoring tools may package up all the essential files and make it easy to export and reimport those files, I don’t think wikis are impractical for translation. Look at Wikipedia, after all. How is it available in so many languages if wikis aren’t suitable for translation? What’s more, wikis allow for community translation in a way that help authoring tools usually do not. Many people from the community can work on translating pages, and they can translate as much or as little content as they want.

Finally, as for the argument that wikis are underused, I think this is because people misunderstand volunteer dynamics. Just adding an Edit button on a page doesn’t mean people are going to edit the content in useful ways. In the same way, if you walk into a room of people and issue a blanket call for volunteers to work on cleaning up the roadside, not many will do it.

Managing volunteers is all about relationships and personal invitations. If you have a group of people who have volunteered to do writing, and you invite them to do specific writing tasks, they do it more often than not. Getting people to participate requires management. It requires some relationship building and follow-up. But it’s possible, and the effects can be somewhat staggering.

I don’t mean to discuss the merits of wikis at length here. Certainly wikis have shortcomings. For example, with Mediawiki, the access model seems a bit narrow-minded to me. You can’t control access at the page level; everything is either open or closed. Skinning themes is also more complicated than it needs to be. But it’s a platform that has many more advantages than disadvantages. And the success of Wikipedia seems to trump all possible arguments against the viability of wikis or Mediawiki as a tool for knowledge.


It’s too early to tell whether moving back to wikis will solve the resource problems I mentioned earlier. But I’m hoping that I will have learned enough about engaging volunteers to make wikis finally work for me.

I know wikis aren’t ideal for every situation. If collaboration isn’t important, if you aren’t stretched thin with resources already, and if your internal technical writing team can adequately handle all the documentation needs, can cover all the various perspectives, issues, scenarios, and other topics that your audience wants to see addressed, then a traditional help authoring tool would be a good fit.

But in my experience, the need for documentation is only growing. The idea that a single writer can adequately provide instruction for a system that thousands of people use — people in different roles, environments, locations, perspectives, and business contexts — is an idea that falls short for me time and again. When I sort through feedback and forum threads, my eyes are open to all the gaps and unanswered questions in my documentation.

Collaboration and interaction are key characteristics of the web for a reason: when you allow others to contribute information, the value of the information grows. It becomes more accurate, more comprehensive, and for those who contribute, the documentation becomes their own. This sense of ownership is perhaps the most powerful effect of a collaborative platform. When your users feel ownership about the documentation, they are more inclined to tend and care for it in the long term. In contrast, internal technical writers often move on to another project after one finishes.

Adobe RobohelpMadcap Flare

By Tom Johnson

I'm a technical writer working for the 41st Parameter in San Jose, California. I'm interested in topics related to technical writing, such as visual communication, API documentation, information architecture, web publishing, JavaScript, front-end design, content strategy, Jekyll, and more. Feel free to contact me with any questions.

  • Dan

    Good post, Tom. Hits close to home for me. We’ve put together a wiki doc solution using Confluence, and actually single source and do translations very well (if I do say so myself…). Currently, we only output to pdf, but are working towards a secure access model for our customers. I’m also looking at ways to export to HTML and facilitate context-sensitive help using those exported pages.

    We do have a small dedicated few within our organization (but outside of tech comm) who edit the wiki content and add value without much prompting. We’d like to have more, though. With a wiki, our team of 2 could scale to a team of 60+ if they just contributed. Even if they don’t, the wiki allows us to be agile and still produce quality, professional documentation with little overhead.

    • http://www.k15t.com Joe

      Hi Dan,

      what kind of solution do you have? Do you know our Confluence exporters?

      Regards, Joe

      • Dan

        Hey Joe,

        Yes, actually we’re using your exporters for our solution. We use the pdf exporter for the pdf doc and then the docbook exporter to assist with translation. Tobias (at K15t) did the custom pdf template and the docbook import that we use. It’s all really cool stuff.


        • http://www.k15t.com Joe

          Hey Dan, that’s good to hear!

          Regards, Joe


          Tools for wiki based documentation

        • http://idratherbewriting.com Tom Johnson

          I wish there were similar export tools for Mediawiki. What I’d really like to find is a tool that exports HTML to XML. It seems like Confluence is better set up for documentation needs.

          • http://www.k15t.com Joe

            Yes, I’d say Confluence is definitely the most handy wiki for documentation purposes. Especially with the whole range of plugins available.

            We use it for software documentation as well as documentation in the engineering environment.

    • http://idratherbewriting.com Tom Johnson

      Hi Dan, thanks for the note about your efforts with Confluence. Translation is something I need to be more knowledgeable about. I’m in the process of translating some wiki documentation into ten languages, so this will give me a better idea of the challenges that surround translation and wiki content.

      I think wikis are preferred authoring solutions in volunteer communities, especially such as the LDSTech community. If we invite people to do things, they usually do them. It requires some follow-up and management, though.

  • http://www.flossmanuals.net adam hyde


    have you considered using booki? http://www.booki.cc- its is a booki-wiki. it is free software and better suited for doc writing than a wiki


    • http://idratherbewriting.com Tom Johnson

      Thanks Adam. I checked it out but their site didn’t explain the product very well. I’m not sure why it’s more suited to authoring than a wiki. However, it’s great to see efforts with collaborative community authoring.

  • http://www.k15t.com Joe

    Hi Tom,

    have a look at our Confluence plugins. They will allow you to single source your wiki by exporting to: HTML, ePub, Word, PDF, EclipseHelp and DocBook.

    Best, Joe

    • http://idratherbewriting.com Tom Johnson

      Thanks, Joe. If we were using Confluence, it would be great to leverage the exporters you’ve developed. Do you have any plans to develop similar exporters for Mediawiki?

      • http://www.k15t.com Joe

        Nope, no efforts on media wiki. We stay focused on Confluence.

  • http://seapegasus.org R.K.

    I agrre with you except for this line:

    “Look at Wikipedia, after all. How is it available in so many languages if wikis aren’t suitable for translation?”

    That’s a strange question to ask since most non-English Wikipedia articles are not translations; they are new articles about the same topic. Wikipedia is not technical writing, articles disagree and different language versions represent the same topic differenly with varying degrees of detail.

    (Granted, many multilingual authors compare their article to more detailed articles in other languages, and use this additional info to fill in the gaps, so a lot of information slowly eventually percolates through to other Wikipedias.)

    In my previous job, we had user-translated documentation, some as static HTML, others on wikis. With community translations there’s always the problem that the language-versions diverge. As long as the users can tell for which version a translation is valid, that is acceptable (our users knew that the translations were a community maintained bonus, and they could switch to the official English article for updates).

    • http://idratherbewriting.com Tom Johnson

      Thanks for pointing this out, R.K. You’re absolutely right that the translations aren’t a 1:1 translation but are separate efforts at the same content. I’m a little surprised that Mediawiki hasn’t developed a more robust interwiki translation mechanism. I’m not sure why.

      I’m curious to know how you kept track of diverging language versions. I assume the English was usually the most up to date. Did you periodically refresh the other language versions with new translations based on the updated English version?

      • http://seapegasus.org R.K.

        “I’m curious to know how you kept track of diverging language versions. I assume the English was usually the most up to date. Did you periodically refresh the other language versions with new translations based on the updated English version?”

        Yes. The English version (static HTML) was the official one (and we also had official localizations of the core doc & help for each release). Then some employees volunteered to maintain wiki contributions in their language. They joined foreign-language user groups for our product and encouraged users to translate specific articles or update wiki pages. They “owned” the ongoing task of encouraging contributors and finding new ones, because external volunteers eventually move on to other tasks.

        It won’t work to reply-to-all “Everybody: start translating!” to a mailing list once. In my experience, you need contact persons who subtly guide the process and keep on top of the evolving wiki. These employees indentify SMEs and ask “You as an expert, please help and localize this particular wiki page”, that works better.

        Just saying, wikis don’t keep themselves up-to-date. OK, maybe Wikipedia has tons of long-term volunters? But here we speak of using doc wikis for enterprise customers, right? Customers actually still have to get work done :-) after searching documentation on our wikis.

        We tech writers want others to spend time writing and localizing stuff for us? Then we better be proactive and accommodating and meet the contributors more than halfway. If your project manager expects to flick a switch and then a wiki magically fills itself with free content, tell him it only works with a dedicated owner (whose time needs to be paid too, but it’s less than paying all the contributors…) 😉

        • http://idratherbewriting.com Tom Johnson

          R.K., thanks for sharing your experience with translating wikis. Your method sounds like a reasonable approach. I have another question. If you translated into 5 languages, did you have 5 separate wiki instances, or were you able to translate all the material within the same wiki? This is a question I’m facing right now.

  • http://www.flossmanuals.net adam hyde

    not to repeat but booki has translation work flows and supports bi-directional output, enables forking of content, versioning, history with diffs, and importing content from the corpus and and and…


  • Megan Roth

    We put our online help in Mediawiki, but the search was poor at best. (For example, if you searched for “Install” it wouldn’t returning anything, even though their were topics such as “Installing the Student App.”) I’m guessing we just didn’t have the right plugins or expertise.

    In response to this, the online help was moved to WordPress. It still has the same design, just in WordPress. The search works much better, but now I am more dependent on the graphic designers who maintain the templates, styles, etc, which I don’t like.

    Thanks for the summary of wiki possibilities and limitations.

    • http://www.iteachwriting.com Rob

      What sort of WordPress plugins do you use for this? I’d love to create some docs/help inside my WP sites to do things like this for small-scale, searchable docs for both software products (user manually stuff) and for organizational literature and policies and procedures.

      • http://idratherbewriting.com Tom Johnson

        The default search in WordPress isn’t that good either. I integrated Google Custom Search in my site to improve findability.

        I have seen WordPress used for help authoring purposes, but I really think that wikis are better suited for this.

    • http://idratherbewriting.com Tom Johnson

      I agree about how bad Mediawiki’s search is. I am exploring an extension called MW-Search as well as integrating Google Custom Search. It’s definitely an issue. One thing I didn’t realize is that search results are segmented into different namespaces, and the default search results only show content from the Main namespace. Talk pages, user page, templates, and other content is not shown by default.

  • http://www.ifcatscouldwrite.com Gina Wadley


    We had wanted to use the Confluence wiki for user docs, but never found a solution to send the files to a Localization Service Provider for translations and get the files back into the wiki properly. You can’t just output to xml or Word, have the files translated and reimport because they can’t filter out the page history and not break the plugins. Wikis are great if you’re a non-profit and can rely on community for translations. But when you’re documenting enterprise software and you need the translations to be exact, you either have to use in-house translators or an LSP. So now we’re going to FrameMaker DITA XML with the DITA Open Toolkit or Adobe TCS 3.5 and RoboHelp for WebHelp and PDFs.

    • http://idratherbewriting.com Tom Johnson

      Gina, thanks for bringing up this issue. It’s something I’ve been trying to figure out. Here’s a solution I plan to try. (We also have in-house translation, and we do not always rely on community volunteers for translation.)

      I plan to create a master page that includes all the pages I want to include in my output. In mediawiki, I can just embed one page in another using {{:Pagename}}. With this master page, I could copy it into a Word document and send that Word document off to translation (our translation department accepts Word documents). When the translation is completed, I’ll use this Microsoft Word add-in to export back to Mediawiki. It will involve some copying and pasting, but since I don’t have thousands of pages to translate, it might work well enough for our needs. What shortcomings do you see with the process I described?

  • Marcia Riefer Johnston

    Nice analogy to road cleanup. Thanks, Tom, for the clear, informative analysis.

  • http://www.protechwriting.com/ Larry Czaplyski

    Biggest problem with wiki information is it is not vetted. Having said that, I use wikis to find information that I’m unable to find other ways. About half the time I find something useful.

    • http://idratherbewriting.com Tom Johnson

      Larry, good point. Couldn’t the wiki owner assign content stewards for each section of the wiki? The problem of not vetting content seems to be more of a cultural one than a tools problem. The tool doesn’t force vetting, but that doesn’t mean a vetting process wouldn’t be set up.

  • Pingback: Curated Post by Tom Johnson: Why I Returned to Wikis for Help Authoring | Content Rules, Inc. (formerly Oak Hill Corp)()

  • http://www.technicallywriteit.com Patrice Fanning

    I agree with Larry. My experience of WIKIs is that the quality of the content is often questionable. I’ve also experienced issues in actually finding the information I’m looking for on bigger WIKIs that lack any kind of logical structure.

    • http://idratherbewriting.com Tom Johnson

      Quality and findability are certainly valid issues for wikis. I do think that there are solutions to both, though. For quality, if you can assign someone as a content owner, chances are the content quality will not suffer as much as when no one takes ultimate ownership of the content (which is often the case). For findability, I find it odd that wikipedia ranks so highly in Google search, but it’s own search isn’t very good. I think integrating Google custom search can be beneficial. Also, at least with Mediawiki, their own built-in search is kind of sophisticated. The results are segmented into various namespaces. Not all namespaces appear in the results.

  • http://www.z0mbiebytes.com Michael McGuire

    We’re running a trial wiki where I work, with the hope we can roll out the concept to others docs and other departments. We looked at MediaWiki, but finally went with FOSwiki for the structured wiki aspects — we’ve only scratched the surface of these.

    Along the way, I’ve been trying to ingest the wiki mindset, visiting sites like meatballwiki, wikiwikiweb, and wiki patterns. The problem is getting the users of the wiki to adopt the same mindset. As always, other projects have intruded on our roll-out plans, but we recognize we need to spend some time just getting in on the wiki and showing by example how to use it.

    We’re trying to vet the content as it comes in, assigning some of our writers as maintainers of certain webs with FOSwiki. Also, everyone from Documentation acts as WikiGnomes. Eventually — we hope — people outside of our team will assume some of these roles, purely on a voluntary basis. We’ve seen some of this happening already in out test project.

    Regarding print, FOSwiki has some plugins for producing PDFs and also packaging the wiki content as html (which could then be rolled into some sort of deliverable; perhaps FAR?). Also, Prince does a good job taking HTML content and making it into a decent enough PDF for print.

    Good luck with the wiki.

    • http://idratherbewriting.com Tom Johnson

      “We’re trying to vet the content as it comes in, assigning some of our writers as maintainers of certain webs with FOSwiki. Also, everyone from Documentation acts as WikiGnomes.”

      I think this is a smart strategy. Ideally, if you can distribute ownership to a wide group of people, you can maintain a large body of content. It takes someone to connect the content owners, content pages, and subject matter experts. I feel like I’m fulfilling this connector role more and more.

  • http://everypageispageone.com Mark Baker

    I’m not a wiki fan myself — I’m a structured text guy bred in the bone — but I am fascinated by the trend, and by the variety reactions to it.

    Wikis started more as a cultural statement than a technology. They were a tool for the democratization of content, the intent being to eliminate the distinction between reader and writer. In the wiki philosophy, every reader was also a writer, there was no ownership of content, and not notion of a final, finished, of blessed editions of content. The wiki was always open, always evolving, and blessed only by the consensus of the community. Today, it would style itself “occupy content”.

    What wikis have become, largely, is an unstructured CMS with only one face. A traditional CMS has two faces: one toward the author, and one toward the reader. A wiki has only one: the same face toward reader and writer, with every page having an edit button on it. Except that today the edit button is locked or hidden from most users. The distinction between reader and writer has been reintroduced and enforced. The original wiki philosophy has been rejected.

    Still, the stated motive of most people who adopt wikis for technical communication is to allow more collaboration and to open up authoring to a wider community. So some shadow of the wiki philosophy is still at work. That being the case, I think there are a couple of things that people need to understand about the wiki philosophy and its consequences.

    The first is, if you want to crowdsource effectively, you need to be open. People need gratification. If the content they contribute disappears into a black hole of moderation and curation, they don’t get the immediate gratification of seeing their work published, and gratification delayed is gratification denied. You won’t get a lot of content from the crowd unless you let the crowd publish.

    The second is a consequence of the first. The implication of the idea that there is no distinction between reader and writer is that the reader has to take more responsibility for what they read. The old contract between the writer and reader of technical content, that the published content had been vetted and could be relied upon uncritically, cannot be sustained in a crowd-sourced world. The reader of a wiki, like the reader of any Internet content, has to assume some responsibility for vetting the content they receive.

    By and large, readers do understand this. It is the responsibility they accept every time they type something in a Google search box. The simple fact of the matter is that reader’s prefer unblessed content that addresses their task and is available now over blessed content that does not cover their task or will not be available until next year. Timeliness and coverage trump all other considerations most (thought definitely not all) of the time.

    The question for tech writers is, is there a place in your hearts, and in your company’s relationship with its customers, for unblessed content that enhances coverage and timeliness?

    • http://www.linkedin.com/pub/marcia-johnston/9/8a4/4a3 Marcia Johnston

      Helpful, Mark. Thanks for articulating these pros and cons so thoroughly and clearly.

    • http://idratherbewriting.com Tom Johnson

      Mark, I like your insight into wikis here. I want to highlight your comment in a new post rather than respond to it here. You bring up a lot of important points about how wikis change the reading experience.

    • http://www.RosehavenCottage.com Cindy Garber Iverson

      Excellent points, Mark. Excellent.

  • Pingback: Wiki Culture, Reader/Writer Distinctions, and Divergence from Structured Authoring | I'd Rather Be Writing()