Wiki as a documentation delivery system?

Subject: Wiki as a documentation delivery system?
From: Geoff Hart <ghart -at- videotron -dot- ca>
To: TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>, Carol Kiparsky <carolk -at- satmetrix -dot- com>
Date: Sat, 29 Jul 2006 08:49:25 -0400

Carol Kiparsky wondered: <<Have you had experience using a Wiki as a means of delivering documentation and getting input from your customers?>>

Nope. But I have done a fair bit of thinking and reading about it. So take my reply as reasonably well-informed (and more than a little expert in the real-world review process <g>), but weight it less heavily than feedback from people who have actually worked with wikis.

<<I plan to start with our internal implementation guides, then expand to external docs on the wiki for internal review, and finally open the external docs on the wiki for customer use and feedback.>>

The biggest problem with "opening" a Wiki is access control. There was an article in _Scientific American_ a while back about the surprisingly intense wars that sometimes arise over updating and revising controversial topics such as evolution vs. intelligent design. Wikis are self-repairing in the sense that the editors get edited, but until someone discovers a malevolent or simply stupid change and fixes it, the disinformation can cause all kinds of problems for those who aren't informed enough to spot the flaws. If the Wiki is published in your company's name, you're responsible for the consequences.

So if you do use something interactive, make quite sure that you provide strong access control. The ideal is a something like a two-phase commit: in the first phase, someone provides comments and suggestions; in the second phase, you or someone you delegate vets the new material and decides whether to add it to the wiki. And don't forget backups: if someone cracks your wiki software (perhaps a competitor doing industrial espionage?), you want to be able to re-establish it in minutes, not days.

<<Our current documentation is WebHelp and PDF, and the formatting used is very valuable in conveying information. Wiki pages have minimal formatting, at least as far as I have seen.>>

So far as I know, formatting limitations are not inherent in the wiki technology. Wikis are based on HTML, which is why you can display them in browsers without installing extra software, but they have additional plumbing added to make them interactive. The first part should be largely under your control, though you may have to do a bit of looking to find a wiki tool that provides the full degree of formatting control that you need. The second part will require a bit of research to find something that provides adequate interactivity.

<<2. What about context sensitive help?>>

Context-sensitive help shouldn't be taken as something mysterious. All it is, at its basis, is the following: "When the user asks for help, the help command/button/whatever displays a topic that describes the current context (dialog box, module, menu choice, icon, whatever)." That link can be a help context ID, or a Web URL--it simply doesn't matter. The only really important things are that the link must be visible and obvious and that it must take them to the right place.

The complication involved in moving from hard disk-based help to something on the Web is how you display the right topic. On your hard disk, it's trivial: there's no Internet connection to establish and troubleshoot, no server problems to account for, recalcitrant firewalls, etc. etc. But once you link outside the computer, you've got a world of troubleshooting you need to account for in your programming. It's not rocket science, but neither is it trivial.

In addition, people who need access to your help while traveling, while working with their laptop unplugged during a thunderstorm, or while waiting 2 days for the network admin to re-establish an Internet connection after a virus takes down the network... Well, not to put too fine a point on it: they're hosed. So the wiki must be supplemented by an equally effective local help system of some sort.

<<Maybe it would be best if reviewers (internal and external) could comment by annotation instead of directly revising the text. Does a wiki support this? Or is it not a good idea?>>

You might be interested in my article on designing a review process, which just appeared in the July/August 2006 issue of _Intercom_. The core of an effective review system is identifying the types and stages of review that you really need, and getting buy-in from all parties involved: managers, reviewers, and writers/editors.

The technological details are so much less important that they're essentially irrelevant. If everyone wants to contribute to effective reviews, you'll get good and timely reviews even if all you have is crayons and pads of legal paper. If not, all the technology in the world won't help. In the absence of a commitment, the problem with choosing a wiki for review is the same as the problem with all documentation: nobody will ever voluntarily look at the material.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --
Geoff Hart ghart -at- videotron -dot- ca
(try geoffhart -at- mac -dot- com if you don't get a reply)
www.geoff-hart.com
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

WebWorks ePublisher Pro for Word features support for every major Help format plus PDF, HTML and more. Flexible, precise, and efficient content delivery. Try it today! http://www.webworks.com/techwr-l
Doc-To-Help includes a one-click RoboHelp project converter. It's that easy. Watch the demo at http://www.DocToHelp.com/TechwrlList

---
You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-
To unsubscribe send a blank email to techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40infoinfocus.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.


References:
Wiki as a documentation delivery system: From: Carol Kiparsky

Previous by Author: Misc: Saints of communication
Next by Author: Acronyms--How often do you spell them out?
Previous by Thread: Wiki as a documentation delivery system
Next by Thread: Re: Wiki as a documentation delivery system


What this post helpful? Share it with friends and colleagues:


Sponsored Ads