Guest Post: Why I Love Wikis
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 (http://knowledgecenter.zuora.