Re: Going Wiki for documentation?

Subject: Re: Going Wiki for documentation?
From: "Simon North" <Simon -dot- North -at- quintiq -dot- com>
To: "SB" <sylvia -dot- braunstein -at- gmail -dot- com>,<techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Fri, 22 Jun 2007 12:52:06 +0200


When I joined this company 3 years ago, we had 50 employees in 2
We now have more than 150 employees in 6 countries and 3 continents,
but only
1 technical writer. The products we sell are very knowledge intensive,
and a lot
of that knowledge was sold in the form of consultancy so there was
animo to put it on paper. In fact, as far as source information for
there was so little it was mind numbing.

I introduced a wiki to spread the documentation effort. Some parts have
very well (a 'solution base' and a 'knowledge base', largely driven by
customer support department), and some have been a disappointing
(trying to persuade R&D to document their c++ class libraries).

I wouldn't call it single source, though I tried to design it to be so
(the C++ source
code comes out of the software, is converted into XML, my XSLT
converts the
raw text into something more meaningful - sorting, reordering, adding
and filtering,
and other XSLT code converts the XML code into RoboHelp HTML, and via
to Word and PDF). There is WordBasic code readily available to convert
documents into wiki syntax (I have some I can offer for dokuwiki
syntax), but
getting material out again is still a problem (I wrote a C program
using Bison that
works pretty well).

Dynamic is a cultural thing, IMNSHO. Putting the tools in place is a
tiny, tiny part
of the equation. It's a wetware problem; you have to do a lot of
evangelizing to
get things to take off (I was fighting uphill at the beginning and even
had to produce
the first prototype on my laptop in my own time ... there was a kind of
Eureka moment
when our CEO discovered that he had an entry on Wikipedia - and that it
was correct).

Some details:
> Pros:
> - Very dynamic, revolutionary, avant-garde

only as much as the users.

> - Structured writing/single sourcing

not necessarily; the technology enables, it doesn't enforce or even
Sloppy wiki content is probably worse than an engineer-written Word

> - Content and knowledge management --> Centralizes the documentation

depends. this is an implementation issue. Virtual centralization is
good; but it
needn't be physical. Centralizing access is the key.

> - Enables the engineers in the company or the customers to write on
the Wiki
>-> enables active participation.

Enabling it will not make it happen.

> - There are lots of macros and solutions to work around the problems
we may
> encounter.


> Cons:

> - Everybody would have to use a new tool that enables to write into
the wiki
> (we would probably not use a free Wiki but a tool that enables all
kinds of
> workarounds to to custom design it to our needs)

Wrong. I use dokuwiki (completely free); it has a flourishing support
very active developers, plenty of plugin writers, and is easy to

> - Conversion from MS Word is not obvious at all and would require
> development.

This really is a trivial issue and the least of your problems.

> - Conversion into PDF is not simple either. Therefore printed
> into a nice format may be an issue.

Is not really that difficult.

Our wiki is now (sigh of relief) an integral part of our internal
communication. If people
can't find something in the documentation, they go to the wiki and very
soon we intend to
'port' part of it to an externally accessible wiki,

There are lots and lots of issues and lessons learned, too much to cram
into a rushed email
mashed during my lunch break. Maybe it's time I put it all together and
wrote a case
study ...

Hope this helps anyway; now if only I could get the CEO to start a blog


This message contains information that may be privileged or confidential
and is the property of Quintiq. It is only intended for the person to
whom it is addressed. If you are not the intended recipient, you are not
authorized to read, print, retain, copy, disseminate, distribute or use
this message or any part thereof. If you have received this message in
error, please notify the sender immediately and delete all copies of
this message. Please note that e-mails are susceptible to change,
therefore they are not binding.

Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include support for Windows Vista & 2007
Microsoft Office, team authoring, plus more.

True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity!

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

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

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.


Going Wiki for documentation?: From: SB

Previous by Author: RE: Writing structured content
Next by Author: Re: Visuals in work instructions: how many is too much?
Previous by Thread: Going Wiki for documentation?
Next by Thread: Re: Going Wiki for documentation?

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

Sponsored Ads