RE: [docbook-apps] [OT] - Doc in Wiki system

["Rowland, Larry" <larry.rowland@hp.com>]

Jan,

I know of a couple of things that might lead an organization to adopting
Wiki technology for their help systems.

  1) User annotation.  One of the things lost when paper went away was the
     ability of users to add their own information to a document.  This is
     important, particularly with complex systems and customizable systems.

  2) Local extensibility.  Many organizations invest heavily in customization
     and configuration of complex software.  Being able to add their own
     information to the local distribution of the help system can be very
     important in this type of environment (instead of saying "log into the
     CMS" it can say "log into the CMS at https://local.system.company.com:280";
     and the more explicit help is, the better).

  3) Allowing the user community to contribute.  If there is an active user
     community, allowing the users to add information that they discover while
     using the product can be valuable, since they may take it into areas that
     the developers and documenters did not have time to investigate.

  4) Reducing development costs.  If you can get the users to write their own
     documentation (or part of it) you don't have to provide as much staff to
     do it.

The first two items have been handled by various technological extensions to
delivery engines over the years, but there is no uniform approach to it across
systems and technologies.  Both of them are issues that have made help systems
less effective for large, complex systems (simpler systems tend not to need as
much of either) and need to be considered when evaluating help delivery
technologies for a project.

The third item is a two edged sword.  People may suggest ways of doing things 
that are not robust, particularly if they are based on incomplete knowledge of 
complex systems.  How is the information filtered if incorrect or misleading
posts are made (a problem with any "crowd sourced" information).  What happens
to the structure of the document over time (something that is not as critical
in information that is always accessed by search, but documents that grow by
aggregation instead of planned development can become quite confusing).  Even
if search is the primary access method, how do you tell which entry is the 
one that is most important for you, and how do you search effectively if you
are new to the domain and don't know the vocabulary yet (a big advantage of
indexes over full text search is that a good index teaches you the terms as
you use it).  Wikipedia has to add disambiguation pages and there are 
frequent discussions of whether pages need to be merged or split among the
authors working on Wikipedia.

I would not expect any company to admit to the fourth reason and it is 
cynical to bring it up, but given the amount of downsizing (or right-sizing
or whatever it is called by the people who are doing it) that goes on in
the tech industry, it cannot be ignored as a possible explanation.

I am sure there are others (including "Wikis are the new buzz" which can
not be ignored), but these are the ones I have looked at when the idea came
up in design discussions I have been involved in.  An important issue that
came up in one of the discussions was legal -- who is liable for information
added to an official document published by a company.  It has a logo on the
top of each page.

Regards,
Larry Rowland

-----Original Message-----
From: honyk [mailto:j.tosovsky@email.cz] 
Sent: Tuesday, June 01, 2010 12:36 PM
To: 'DocBook Apps'
Subject: [docbook-apps] [OT] - Doc in Wiki system

Helo Everyone,

I've found one company which is switching their on-line help into Wiki
system. Is this a trend, fashion or are there really some requirements not
available in conventional channels?

I've found one article with the nice comment from Mick Davidson
http://ffeathers.wordpress.com/2009/09/14/getting-content-into-and-out-of-wi
kis/

It seems to the user more comfortable, but for me, at author side, quite
scattered. I am asking myself: If version 1.0 of product will be released
and help spread via WIKI and many users will add there their comments and
responsible persons on other side give them responses in form of comments,
what will happen with all this messages when version 2.0 of the product will
be released? 

From my point of view all comments, if relevant, should be added immediately
also into Help source (both actual 2.0 'trunk' and on-line 1.0 version
should be synchronized). Yes, at the end this is beneficial, it makes next
version of documentation more clear and user friendly...

I see in the background system like docbook. Is docbook still the right
choice? Or will be these wikis created directly without any other sources?

I already understand to some recent needs for DocBook-Wiki round-trip. I
will be soon at the same situation...

Any comments or experience are welcomed.

Regards,

Jan


---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org