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

[<Cavicchio_Rob@emc.com>]

I think that Jan's original question is also very significant; namely,
what happens to user-generated content on the version 1.0 document when
version 2.0 comes out? Some 1.0 user-generated content will still be
relevant in 2.0, and some won't. It seems to me that this leads to a
real rat's nest of possibilities, none of them particularly appealing:

- Does user-generated content stay with the version it was created for?
If so, how do users of the next version know that it is there? How do
they tell which items are still relevant and which aren't?

- Does user-generated content get blindly migrated from one version to
the next? If so, then again, how do users know which items are still
relevant--or indeed, that there are any that are *not* relevant.

- Does a company pay someone to filter through user comments and migrate
the relevant ones to the new version, either folding them into the
documentation proper or just carrying them forward as comments? Seems
like the "right" thing to do for the users, but depending on the size,
complexity, popularity, etc. of the doc. set, it could be a monumental
task.

- Are users given the tools they would need to sort through previous
comments and migrate them forward as they see fit? For
community-accessible docs, what if different community members disagree
about the status of the various comments?


> -----Original Message-----
> From: Rowland, Larry [mailto:larry.rowland@hp.com]
> Sent: Tuesday, June 01, 2010 4:14 PM
> To: honyk; 'DocBook Apps'
> Subject: RE: [docbook-apps] [OT] - Doc in Wiki system
> 
> 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-o
f-
> 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