--- title: "Guest Post: Why I Love Wikis" date: 2012-04-14 description: "$( document ).ready(function() { // Handler for .ready() called. $(" canonical_url: https://idratherbewriting.com/2012/04/14/guest-post-why-i-love-wikis/ --- # Guest Post: Why I Love Wikis The following is a guest post by Neal Kaplan, a technical writer at Zuora, Inc. [![](https://s3.us-west-1.wasabisys.com/idbwmedia.com/images/orangebar.png)](https://s3.us-west-1.wasabisys.com/idbwmedia.com/images/2009/04/orangebar.png) 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.