Re: Wiki as a documentation delivery system

Subject: Re: Wiki as a documentation delivery system
From: "Simon North" <Simon -dot- North -at- quintiq -dot- com>
To: <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Mon, 31 Jul 2006 13:54:03 +0200

I work for a software development company where word-of-mouth
information exchange is/was not just the
usual state of affairs, it was/is company policy. Coming into the
company to bring order to the documentation,
it bothered me that there was so little legacy information to work
with. A lack of written documentation is
not necessarily a bad thing in a small company, but the company has
quadrupled in size over the last 2 years
and we now have offices in 5 countries and 3 continents.

I introduced wiki (dokuwiki) as an additional documentation platform to
encourage feedback and additional
contributions, but also for knowledge capture. The wiki has been
running for about 9 months and is slowly
fulfilling all its promise. Currently, it's on our intranet, but
'partner' company employees (who are more or
less our customers) have access. I have plans to migrate towards an
external internet wiki in due course,
but we aren't ready for that yet.

In adopting a wiki, I was all too aware of the potential problems of
taking on a new platform/medium/format.
As the only tech writer in a company of nearly 200 people, a dead-end
format is the last thing I need.
I therefore opted for dokuwiki because of its flat file storage system.
This allows me to batch convert whole
directories (namespaces) of documents to and from
Word/RoboHelp/HTML/XML. Admittedly, I had to write
some of the conversion packages myself, but there was a lot of code on
the Web that gave me a head start.

Formatting hasn't been a real problem. Help topics are not exactly rich
in formating, and neither is wiki. I import
Word, XML (from C++ class code and descriptions), HTML into the wiki,
and I export HTML and XML. I import the
XML into RoboHelp, and from there I create WebHelp and PDF (via Word
and Acrobat).

Opening up the source files to editing has been the least of my
problems. In fact, I still have to campaign actively
to solicit edits. The fact that I can see who has edited a page, when,
and what they did gives me a richness in change
tracking comparable to what Word provides. Furthermore, I can roll back
to any previous version, right back to
when the document was created. Dokuwiki also allows me to include HTML
code, and I can link to local shares
if I simply want to add a link to a document on a server. I haven't
had to enforce an annotation convention, though
I do use one myself when I want to make it extra obvious that I am
making a personal comment.

The only aspect I have to invest additional work in is navigation. I've
been able to contain the 'damage' by separating
areas out into dokuwiki namespaces (read, folders), but despite some
fancy XSLT code, I still need to go back into
RoboHelp and add a lot of navigation links. In itself, this isn't too
much extra work though as I have designed the RoboHelp
application to be single-source (I use conditionals for print and
online versions, have a firm hierarchy of descriptive/procedural
topics, and have topic templates that break down into descriptive,
screen, procedure, and navigation blocks).

I think the biggest problem I faced was during the initial stages. I
didn't want to make the wiki publicly available without
a useful amount of content, but I found I couldn't create enough useful
content without going public. After a slow introduction,
I think we have almost reached the point where the wiki is
self-sustaining and you can almost see the value of the content
increasing as the days go by.

Hope this helps,

Simon North




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.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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:
Re: OT: Wikipedia as a reference source: From: Dick Margulis
Wiki as a documentation delivery system: From: Carol Kiparsky

Previous by Author: Re: ISO 26514 draft ready for comment [long]
Next by Author: RE: (no subject)
Previous by Thread: Re: Wiki as a documentation delivery system
Next by Thread: Robohelp X5 and Broken Links


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


Sponsored Ads