TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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.
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
