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

["honyk" <j.tosovsky@email.cz>]

Thanks to all for sharing your experience! I am already convinced, Wiki is
my goal... but it will be just one of the outputs from DocBook source :-) -
it will fill the 'Online help' gap (besides CHM and PDF outputs).

Btw, Lars, your system is very similar to the idea I've tuned in my mind
independently. It is nice to hear that such a system already works for
somebody and to know possible problems that can arise (I like the idea of
scanning comments). Moreover, I plan to use the same wiki ;-)

My idea is to automate DB->WIKI conversion as much as possible. I've
analyzed the Confluence XML import format, quite complicated, but I can
imagine (in one day) I'll be able to "chunk" my large document into separate
Wiki pages with keeping all the hierarchy with all the images attached. (I
cannot imagine to import all the separate pages and to create the hierarchy
manually). The only parameter I need is (probably) ID of the index page of
newly generated Space (for navigation). 

My future workflow: Create a new Space in CF, export its content into XML,
grab ID of the index page, transform DB source with this ID passed as
parameter into XML, attach and rename all the necessary images, compress all
that stuff into the zip file and then import that file into CF. Now the
newly created space should contain wiki presentation of my document - ready
for user comments and so on.

For this approach it would be ideal to generate the Wiki code directly from
a DocBook source, not via temporary HTML pages. I am just evaluating
stylesheets for MediaWiki output:
http://sourceforge.net/tracker/?func=detail&atid=373749&aid=2839219&group_id
=21935

I am determined to continue investigating this topic, to try to implement my
ideas and we will see, if it is the way or not. Of course, I'll share my
experience.

Regards,
Jan


> -----Original Message-----
> From: lars.bjerges@swedbank.se [mailto:lars.bjerges@swedbank.se]
> Sent: Saturday, June 05, 2010 4:15 PM
> To: docbook-apps@lists.oasis-open.org
> Subject: SV: [docbook-apps] [OT] - Doc in Wiki system
> 
> What we do is publishing internal development handbooks (So it´s not
> really on-line help but the process might be more or less the same) in
> a wiki-system by means of generating content from DocBook.
> 
> We use Atlassian Confluence and the way we do it is as follows:
> 
> o If a DocBook document is created with base "article" it will generate
> a one-page wiki entry.
> o If the source is based on "book" it will be a multipage wiki document
> (Confluence has a hierarchic structure for its pages).
> 
> The reason for this is that we don´t think it would be nice to generate
> a document consisting of a couple of hundred print pages into a one-
> page html document.
> 
> If images are used (gif, jpg, png, svg) they will be added as
> attachments to the wiki-page that uses them. In the case of svg we
> convert them to png before they are uploaded.
> 
> All generated wiki-pages will get special wiki-labels and the format
> will be more or less standardized. At least the parts that deal with
> "meta-data" e.g. document owner, document maintainer, version and so
> on.
> 
> If comments are added by wiki users we have developed a wiki-scan
> process that collects these and it is up to the document maintainer to
> either incorporate or disregard them in future document versions.
> 
> The transformation is Docbook "source" -> html/chunked html (standard
> transforms) -> wiki source (own-written stylesheets).
> 
> There is also a possibility to generate PDFs and if, for a specific
> document, a PDF is generated a "print-off" link will be added to the
> documents wiki-page.
> 
> The usage of chunked html will put some careful planning into the minds
> of the authors since their decomposition of a document, and also the
> chunking strategy, will obviously affect the reading experience of the
> end user.
> 
> Up to now the generation process has been done manually by a
> "librarian" function but we are in the process off automating it by
> doing nightly generations of updated documents stored in cvs.
> 
> Lars
> 
> -----Ursprungligt meddelande-----
> Från: Cavicchio_Rob@emc.com [mailto:Cavicchio_Rob@emc.com]
> Skickat: den 2 juni 2010 21:58
> Till: docbook-apps@lists.oasis-open.org
> Ämne: RE: [docbook-apps] [OT] - Doc in Wiki system
> 
> 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