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.
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
Sylvia,
When I joined this company 3 years ago, we had 50 employees in 2
countries.
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
little
animo to put it on paper. In fact, as far as source information for
documentation
there was so little it was mind numbing.
I introduced a wiki to spread the documentation effort. Some parts have
worked
very well (a 'solution base' and a 'knowledge base', largely driven by
the
customer support department), and some have been a disappointing
failure
(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
there
to Word and PDF). There is WordBasic code readily available to convert
Word
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
promote.
Sloppy wiki content is probably worse than an engineer-written Word
document.
> - 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.
True.
> 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
community,
very active developers, plenty of plugin writers, and is easy to
modify.
> - Conversion from MS Word is not obvious at all and would require
some
> development.
This really is a trivial issue and the least of your problems.
> - Conversion into PDF is not simple either. Therefore printed
documentation
> 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
...
Simon.
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. http://www.DocToHelp.com/TechwrlList
True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
