Everyone, please give the TechWriterVoices.com site a look or two or three or more. It’s such a great site. I’m not just saying that because I have a podcast there now, Answering Tough Questions about Wikis – Anne Gentle, but because I do want to tell everyone what a great interviewer Tom Johnson is.
Tom sent ten excellent questions ahead of time via email and I spent some time answering them by writing out some notes. I’ve sharpened them up for those of you who, like me, don’t really have the auditory learning style that listening to podcasts serves best. I always want to be able to scan my media and pluck out the pertinent tidbits, and few podcasts have that feature. (Side note: with QuickTime movies you can make chapters which allows you to scan the chapter titles for the content you’re most interested in.)
So, here’s the interview in text form, but not a complete transcript. We skipped around, Tom edited around the audio difficulties, and sometimes I just answered the question differently.
1. How we can manage and re-use content when it’s wrapped up in mediums like wikis? Can you single source topics? Can you export the content to Word? Or is it locked in its own format?
Nice lead in. This is the ultimate question that many people are asking me and I am having lots of conversations via email and lunches, trying to come up with ideas.
Wiki engines are becoming more and more powerful and CMS-like. WikiMatrix.org has 95 wiki engines listed as of this week. Yes there are still very simple wikis but there are also people making wikis run really powerful websites with amazing wiki extras – like threaded comments, conflict resolution, and so on.
But about single sourcing and wikis…
One idea is that you export your source to a wiki, and then when any changes come in, have to have a human cull through all the edits and figure out what should go into your souce files the next version of the wiki should be, like book publishing. This method is similar to going through support forums or support call logs to see what you’ll include in the next version of your book. Lots of work and thinking.
Another idea for single sourcing a wiki is that the wiki files themselves are the source – if we could invent a DITA wiki where a webform is used to edit DITA topics then we’re there. The wiki platform would also become a publishing engine. Also Confluence appears to work on this idea, that the wiki files are the source and you can publish out to PDF.
Paul Kandel at Intel has this idea that you’d have an offline wiki, with synchronizations every once in a while (you’d set the time parameters). He’s talking about the Dojo Offline Toolkit ( http://dojotoolkit.org/offline), which is based on Google Gears (http://code.google.com/apis/gears/ ), could provide an outstanding solution to the issue of generating offline doc formats. You could enable the wiki itself to be viewed offline, and user additions could automatically synchronize with the online version. I’m not sure I fully understand the advantages and disadvantages here, but the source could be “frozen” in time every once in a while.
Another idea is to be very selective in what you put in a wiki, and make the wiki the source for that selective info only.
Many wiki platforms have import and export capability. However, as my co-worker Mary said on the Author-it users Yahoo group, try not to have your precious content be downstream, meaning, if someone asks you to export all your Author-it topics to Word so that they can be imported into Wikimedia, try to find a way to have the content go the other way around (export Wikimedia content and then import it into Author-it).
I’m also working on the One Laptop Per Child project which is an education project to provide opportunities for children to explore and express themselves. It’s a neat project where we would really like to figure out how to go from wiki content to Author-it and then use Idiom for translation… but it’s probably a “copy from the OLPC Wiki and paste into Author-it” method because the wiki.laptop.org content is not written for the audience we have in mind. The docs for the kids are translated into at least seven languages. It’s an interesting project to be on, and I’m learning so much as I go.
2. You found that with Wikipedia, fewer than 1 percent of users contribute more than half the edits. Should technical writers expect the same 1 percent user contribution effort with the wikis they create?
I just read on keycontent.org that even the MSDN wiki has 5 top contributors. Of the 1876 contributors, 5 contributors (three from Microsoft) made about 1500 of the edits (out of 5800 edits). I believe you should expect a similar contribution effort as long as those numbers continue to be displayed in other wikis. I suppose the key is recruiting and maintaining relationships with those users. And really, you probably want just a few core inner circle type of people so that you can maintain positive relationships. It’s like an active listserv – you can probably count on one or two hands who the inner circle of contributors are. Those are your experts who are also helpful and giving.
3. If it’s only 1 percent, and your audience is 500 users, that’s only 5 people making edits. Is the wiki even worth it then?
It’s certainly worth it to the 5 contributors who are motivated for whatever reason. And the audience size is difficult to speak to the value – if your manuals had an audience of only 5 people, would you write them anyway? In some cases, yes, because many products need the manual for quality purposes – it’s just an expectation of a software or consumer product. For some products, a wiki is an expectation (probably as an extension of highly visible/visited forums).
I write more about motivations for contributing to wikis in this article on The Content Wrangler. (Think of Reciprocity, Reputation, Efficiency, Attachment to a group).
4. What type of information is a wiki best suited for? Reference? Troubleshooting? Living documents? Why?
I believe that there are several reasons to use a wiki for certain types of information. For Reference information, a wiki is searchable and allows for easy upload of large log files (although if the reference info is in tables, well, I’m not sure how each wiki engine would handle table formatting). Troubleshooting info in a wiki follows the “better than a support forum” model for wiki building. A document that changes often or should change often might be suited for a wiki. Internally, developers can use wikis to explain why the software was designed the way it was, what gotchas in the code to be aware of. Wikis are quick methods for team meeting note-taking and that sort of thing, which would be reference info. So I guess the type of information is the type that people want fast and want to collaborate on.
One person on Gordon McLean’s website onemanwrites said that a wiki plus a Google search appliance is a really good thing. I found that to be the case at BMC for the internal wikis and searching, the combo was killer for finding info or for finding collaborators quickly. That commentor also had the good sense to say “it’s worth watching what goes into it to guard against people setting bad advice in stone.”
5. Is the typical wiki editor robust enough to support all the complicated styling that technical writers do? Can you create your own styles? How hard is it to work with graphics?
Some wiki engines are robust enough… lots of technical writers that I talk to like the Confluence editor’s robustness. I’m not sure if technical writers do much complicated styling really, compared to magazine layouts and glossy brochures. Or if we do need complex styling, the copy is sent to layout.
I’m also not sure how complex tables are in most wiki engines. I think for the most part, you get headings, paragraphs, and lists. Beyond that and levels of those, what else do you need for much technical writing?
Graphics can be a complete bear to get in… apparently one of the Motorola writers had a heckuva time importing the graphics from the user manual into the Mediawiki-based wiki with the time crunch she was up against.
6. Who is actually using a wiki? Have you personally used a wiki successfully for a product?
Many people are using wikis internally. I myself was more interested in wiki use externally for product documentation, and interviewed Emily Kaplan at Motorola and Dee Elling at Borland for information about technical product documentation house in a wiki or wiki-like structure. Harry Miller at Microsoft also interviewed one of the PMs for the MSDN wiki.
Wikis are a favorite quick website set up for many open source-type projects. Also the gaming communities seem to have flocked to wikis either as a replacement or enhancement to customer support or game discussion forums.
I’m using www.imiscommunity.com for my current job, and it’s highly effective for making quick web pages for internal or external use. Plus the search engine is useful. It’s a Drupal site but nearly every page has an Edit tab, so it’s wiki-like.
7. Wikis have been around for 10 years. Wouldn’t they take off if they were going to?
I think they have taken off in certain circles, just not yet in ours. I think that with a set of best practices or push from customers or employers, wikis will be in demand, and it’s a matter of positioning your tech pubs department as the overseers of that content. Without a strong guiding hand, a wiki isn’t that useful because people don’t know what to contribute or how to handle revisions and so forth.
8. What if a user makes a change you don’t like? Do you change it back, offending the contributor? Or do you leave it in, offending the other users? How long do you stick around making these decisions?
I think that you almost need to think of the contributor as a team member, and then behave as you would with a colleague writer. If it’s inaccurate, you change it and reason with the person as to why it has changed. If you’re looking to save time, or don’t have the time to arbitrate, then don’t take long to make those decisions, or don’t get involved with that particular change. But don’t expect to build a wiki and have all these contributions come for free or little resource or time investment. That’s just not realistic.
9. How does a wiki build community?
In itself, a wiki can’t build community. There’s a great quote from Wiki for Dummies with a heading entitled something like “don’t go on a wiki suicide mission.” It says “Wikis don’t have magical powers. They cannot create camaraderie where none exists, nor can they streamline an out-of-control operation. They are not powerful information magnets, nor will they make your team better writers, more organized, or more intelligent. In short, without a strong guiding hand, wikis are useless.
Wikis cannot promise instant returns or unbelievable creativity. Wikis allow users to quickly and easily update and upload information.”
I enjoyed the heck out of that quote. But, many web workers are finding that a wiki is a place to find other like-minded individuals trying to tackle the same problems and offering similar solutions, much like a customer support forum. So a wiki can help build community by offering information and identity to the contributors.
10. As a technical writer, are you ever done with a wiki project?
I’d say No. Wiki building is a lot more about relationships and connections so you’d never want to sever those ties if there’s still a bond there. Anyone who thinks that starting a wiki will make less work for their techpubs team by crowdsourcing the writing is fooling themselves. But if you want to serve and connect with a certain set of customers, you’ll do what it takes to keep the wiki alive and kicking.