RE: Wiki as a final output of the documentation?

["McLauchlan, Kevin" <Kevin -dot- McLauchlan -at- safenet-inc -dot- com>]

 Lech Rzedzicki asked:
> 
> I am likely to be tasked with updating and revising some 
> documentation which
> is currently stored in a wiki in a chaotic form.
> My task would be be to improve on the structre, usability etc 
> and I know
> exactly what to do to make it better.
> However, I fear, that if I keep the final output in a wiki, 
> it will quickly
> deteriorate into it's old, chaotic and poor form.
> Instead, I would like to write up a set of tasks in DITA, structure it
> nicely and publish it on a web page.
> Should the documentation need updating (which would likely be 
> very soon), I
> would want to trigger a defect in bug tracking/version 
> control sstem that
> they use for software being documented.
> So my idea would be a more static HTML output from DITA 
> rather than wiki,
> but what this means is a lot more complicated process than 
> what is in place
> right now - i.e. just updating wiki.
> 
> What are your thoughts on this, which is likely to better in 
> the long run?

My thoughts are:

 - Wikis are nifty
 - Wikis can encourage a lot of participation from people who know the
subject
 - Wikis allow nuggets of knowledge to be revised and dressed up for
language, structure, etc.

But

 - Wikis can encourage a lot of participation from people who don't know
the subject as well as they think they do
 - Wikis need a "final arbiter" or "final authority", and they need that
person (or designate) to be on top of the beast, constantly, to keep it
from sliding in undesired directions. In a restricted-access situation,
you don't have to worry about vandals, but there's still an element of
control that's required.

People stop participating if the model is to hold all
submissions/changes for approval, and then the approval is not swiftly
and reliably forthcoming.

You can try to minimize your supervision requirement by locking pages
when you think they've reached perfection, but too many such locked
pages begin to dissuade general participation from the people whose
participation you need.

A growing, evolving wiki is a job for the overseer, and likely the kind
of job where you don't get vacation - or you get a lot of catch-up work
whenever you return from any little departure.

Where does the buck stop?

 - Kevin
The information contained in this electronic mail transmission 
may be privileged and confidential, and therefore, protected 
from disclosure. If you have received this communication in 
error, please notify us immediately by replying to this 
message and deleting it from your computer without copying 
or disclosing it.


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

ComponentOne Doc-To-Help 2009 is your all-in-one authoring and publishing 
solution. Author in Doc-To-Help's XML-based editor,  Microsoft Word or 
HTML and publish to the Web, Help systems or printed manuals. 
http://www.doctohelp.com

Help & Manual 5: The complete help authoring tool for individual
authors and teams. Professional power, intuitive interface. Write
once, publish to 8 formats. Multi-user authoring and version control! http://www.helpandmanual.com/

---
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 http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


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
http://www.techwr-l.com/ for more resources and info. 

Please move off-topic discussions to the Chat list, at:
http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat