Guest Post: Why I Love Wikis

Neal Kaplan

Neal Kaplan

The following is a guest post by Neal Kaplan, a technical writer at Zuora, Inc.

Another post about wikis? Why not! Wikis are great!

Just to set the stage, I’ve been a technical writer for a while now, working for software companies in Silicon Valley. (In fact, I often forget that there are technical writers who don’t document software.) I’ve worked at large companies, where I delivered my source files to a production team and then moved on to the next project, and as a team of one, where I was in charge of writing, producing, and delivering PDFs and online help to the end users. I consider myself an expert user of FrameMaker and RoboHelp.

And I’m happy to leave both of them behind.

Falling in love

Back in 2005, I had the opportunity to join a video game company (!!!) as a technical writer. I was in charge of documenting how to use game engine for an internal audience of game developers. They had a wiki with a small amount of information (written by programmers), which could be accessed from the game development application, so it served as online help.

This was a new world for me, and I loved it! No more lengthy production process (waiting for Frame to build books, then troubleshooting when it hung on a misplaced tag). Instead, I could publish the documentation as soon as I wrote it. When users found errors (it happens even to the best of us), I could fix them immediately, instead of having to file them away and wait to make them available with the next release of the product.

Better yet, I could ask the readers to help. I found that most people were more comfortable sending me a list of suggestions, but I did get a few people to help with tips and best practices. That information almost always comes from your advanced users, and it’s the information that they love to share.

But wikis aren’t exactly online help, and using them solely as a help system limits their usefulness. Even if many users don’t contribute, every user can contribute if they want to. They don’t need to own a copy of the authoring application, or climb the steep learning curve that comes with many of our tools.

Absence makes the heart grow fonder

When that job ended, I went back to a traditional Frame-to-PDF environment. And I couldn’t stand it. What user wants to read 1500-page PDFs? What writer wants to have to regenerate a book that big, with 20+ chapters, just to fix a typo on page 835?

And what happens to the PDFs? You write the content, generate the file, then check it in to be included with the software or post it on the company’s web site. And that’s when it falls into the abyss of the internet: Does anyone read it? How much do they read? Did they find it useful, or as a foolproof cure for insomnia?

Another opportunity to work with wiki-based documentation came my way, and I leapt at the chance. So far, I’ve merged two existing wikis into a shiny new wiki. I moved to a hosted system, using Mindtouch TCS, because it offers a clean, easy to use system with built-in templates, rating and commenting, and a straightforward way to build a documentation hierarchy.

While I was moving the existing content to a new wiki, I was pushed into a “social knowledge” project, where we bribed people across the company to document answers to frequently asked questions and best practices. I admit that I was wary at first: It’s one thing to have people make edits to your documentation (which you can easily review and fix, if necessary), but it’s a frightening new world for tech writers when anybody can write documentation! (Fortunately, wikis come with revision histories, and the ability to revert to a previous version. I’ve only had to use that once or twice.)

Of course, this is the whole point of wikis, and this project produced great content that would have taken me years to research and write. I found that while some people might object to criticisms about grammar and word choices, they were happy to help if I asked them to clarify an explanation or provide an example. I’m fortunate to be in a situation where my coworkers are one of my audiences, and they understand the need for good documentation.

A handful of employees continue to contribute documentation. Some people write lengthy topics, and some provide quick tips and best practices. All of this is hugely valuable to me, and to my readers. The next step is to encourage our customers to contribute to the documentation.

But on the other hand…

Obviously, I love working with wikis. But I will admit that they aren’t perfect and don’t solve every documentation problem.

Structure (IA and Content Strategy): One thing became clear to me soon after I started using a wiki to create documentation: A wiki is not a documentation set, and it’s not exactly online help. I realized that I needed to learn more about web structure, and that meant learning about information architecture and content strategy. IA is probably more directly relevant, but the concepts involved in both areas help me figure out how to design a structure that makes sense. Or at least identify when a structure doesn’t make sense. In fact, I’m in that position right now: my next big-picture task is to rebuild my doc site to have a more meaningful structure, instead of being mapped to our product’s UI.

Curation and Content Management: Without someone acting as curator, a wiki will very quickly collapse into a mass of unlinked, unstructured topics. Once you have built the structure, you need to keep track of what people are writing, and where. At a minimum, you will need to review new topics to add metadata.

For example, with Mindtouch I can add tags to topics, and they control what appears in the Related Topics area. This is hugely valuable, but it means that the tags need to exist, and that writers are consistent in their use of tags.

Single Sourcing: Wikis aren’t known for their single-sourcing functionality. Every wiki that I’ve worked with has a way to pull information from one topic into another, but it’s a manual process. This is manageable on a small scale, but I can see it becoming a problem once I have more writers working on more projects.

Here’s my shameful secret: I’ve been trying to avoid DITA. It just seems too complex for me to bother with, and I was there during the early, terrifying days of Frame-to-help conversion tools. I don’t need to reuse large amounts of content (so far), and I don’t want to get stuck writing dry, contextless snippets of information. I’m not writing massive guides for IBM servers, so why do I need the headache of DITA?

Obviously, that’s just the (mis)perceptions of someone who has only skirted the issue. I’ve talked to other writers about single-sourcing workarounds that they’ve implemented, but I haven’t come across an easy, automated solution to single sourcing to a wiki. Maybe I’ll have to give in and embrace DITA…but I shudder at the thought!

Ending on a positive note

I don’t think that those problems are insurmountable, or unique to wikis. All documentation needs a solid structure, after all. And there are huge advantages to being able to publish immediately and allow your readers to easily rate and comment on your documentation.

Many wikis also provide basic statistics about your documentation, such as a list of popular pages (based on page views and/or page ratings) and topic aging reports. It was easy for me to create lists of the most recently edited and the most popular topics and display that information on the front page.

Mindtouch TCS also provides information about search terms and results, which allows me to identify gaps in the documentation and improve the search results. For example, if users are searching for a term and not finding the correct topic, I can configure that search term to return the result that I want them to see.

Plus, it includes the ability to save topics to PDF. Any reader can save a single topic, or a topic and all of its child topics. It’s easy to create a PDF containing every topic in the Knowledge Center (and a few people have asked for that functionality). Of course, I update the documentation daily, so those files are almost instantly out of date. But that’s a limitation with any static document.

I’m also using Google Analytics with my documentation site, which gives me an enormous amount of information. Besides getting more information about the number of people visiting the site, I can track how users are navigating through the documentation, which browsers they’re using, what screen resolutions they’re using, their language settings…basically, information that helps me determine what I need to support, and what I can do to make the documentation better for my users.

I’ve just hired a second writer. I’m excited to be working with another tech writer, and I’m looking forward to launching a new doc structure, getting more systematic about adding links and tags, and finally getting serious about adding videos to the site.

Neal Kaplan is a principal technical writer at Zuora, Inc., in charge of the Zuora Knowledge Center ( Five of his 17 years as a technical writer have been spent working with wikis. Even after 17 years, he feels that there’s still a lot to learn about writing great documentation. Neal lives in the San Francisco Bay Area with his wife and two daughters, and can be contacted at

Madcap FlareAdobe Robohelp

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.

  • Steve Arrants

    I wonder about the costs. We priced out a similar system from another company for our appx. 2000 user base. At around $20,000 a year in licensing costs, we can in no way justify it. User participation is important, but at what cost?

    • Neal

      I can’t speak to exact pricing (it’s going to vary, of course), but we’re paying a fraction of that for 100 author licenses. I’ve assigned 60 of them so far, and I have about 12-15 regular contributors. For $20,000 to $30,000, you’re looking at enterprise-level support for a much larger number of writers, where the wiki system will be replacing many FrameMaker, RoboHelp, Flare, or other licenses.

      I just hired a second tech writer, and we are paying more than what two FrameMaker/RH/Flare licenses would cost. But those dozen or so other contributors are product managers, customer support reps, professional services, etc. There’s no way that I could ask them to write something in Frame!

      As an example, we have a couple of self-implementation guides. I act as a sort of general editor: I build a structure, do some technical troubleshooting, and then make an editing pass once other people have created content. We have about six people writing content for each guide, and that’s a job that I just wouldn’t be able to do on my own.

  • Steve Arrants

    I am the lone writer for 11 products (many related and sharing text and graphics). The $20K price tag for for another Wiki system, and the price included licensing for 1000 users, additional extensions, and templates. I was told by the other company that anytime a user comments or adds content to the Wiki, they count as a user and would need a license. The 1000-2000 figure are ballpark figures for users who *might* participate.

    It is very frustrating to see and hear everyone rushing to these “solutions” and no one talking about costs–even generally. I tried bringing up the question during a recent webinar, but was shut down. It’s like nailing jelly to the wall.

    • Neal

      Hi Steve,

      Please see my response to your first post. I hope I answered some of your questions. I know that Mindtouch offers multiple levels of service, and the price you’re quoting is for the enterprise level of service. I started with the Starter level, which allows for three authors. Once we needed more features (more authors and a custom URL), we moved to the second tier, which is still significantly less than $20,000 a year, and less than what it would cost to buy HAT licenses for 10 or more authors.

      Of course, you can still download wikis for free, and then deploy them yourself (probably with help from your IT department). Obviously you’re incurring a cost in terms of your time (and IT’s time), but that’s the trade off. In my case, it made more sense to have someone else host the system.

      If you know that you will be the only person who will be writing content, then you definitely need to look for lower-cost solutions, and a wiki might not be the answer for you. For me, I’m looking at a growing documentation department, and the need to allow non-writers to add content to the site. This has been internal users so far, but our users are already rating and commenting on pages. I want to keep going, and recruit users to write content, too. A wiki is the best solution that I’ve found that can meet those requirements, and a hosted wiki means that I don’t have to spend my time keeping the site up and running.

  • Steve Arrants

    Thanks for your help, Neal. The big cost for us will be occasional contributors who take up a license. How are outside contributors viewed by Mind Touch? I mean, if a user contributes to the documentation does he take up a license? Or is he just commenting and someone else curating/editing his content?

    • Neal

      There are two general types of accounts in Mindtouch: Community Members and Authors. If the site is open, then anyone will be able to read your documentation (my doc site is like this, but you can also have it require users to log in). If your users want to rate and/or comment on pages, then they create Community Member accounts, and you can have an unlimited number of those. If a user (internal, external, whatever) wants to edit a topic or create a new topic, then they need an Author account. Author accounts are limited (to 3 in the starter edition, and 100 in the mid-level version we’re using). However, you can grant and revoke those rights as needed, and recover the Author licenses.

      Your point is valid: You have to give out those precious Author licenses if you want people to be able to create new content, or edit existing content (more than just adding comments). We have 62 authors so far, so I’m not facing a real problem now, but I will have to be careful about granting licenses in the future once we expand, and when we want to allow users to contribute content.

  • Ellis Pratt

    We’re fans of wiki-like authoring environments. It’s important to remember not all wikis are like Wikipedia – some are radically different.

    • Neal

      I probably should have mentioned that, too, Ellis! Having worked with different wikis, I know that they differ in significant ways, but of course most people are probably familiar with wikipedia, and not much else.

      One big difference is permission controls: Mediawiki, which is what Wikipedia uses, has a philosophical problem with permission controls. Which makes sense for what it’s used for: They believe that information should be freely available, and locking it down goes against the purpose of a wiki. So the permission solutions that I’ve seen for mediawiki are a bit of a hack, and aren’t easy to implement. This became a problem when we wanted to restrict certain areas of the docs to specific customers.

      Obviously, this isn’t a limitation for companies that don’t need to restrict their docs, but I also use it when I’m writing to be able to hide topics until I’m ready to publish them.

      • Tom Johnson

        Neal, what solution did you use to implement permission controls with Mediawiki? I currently have the same dilemma. I’d love to know that there’s a hack out there that works. I have seen a couple of extensions but haven’t tried them yet.

        • Neal

          Tom: We didn’t have a way to do this with Mediawiki. Everything that I looked at seemed very difficult, at best, and then I kept reading about security holes in those solutions. That, and the lack of other features that I wanted (a decent page rating system, for one) pushed me to find another doc solution.

          (Sorry for the delay, but I always forget to check that “notify me” option!)

          • Tom Johnson

            Neal, thanks for following up on this thread! Better late than never.