OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-apps message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

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.


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

- 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
> Wiki technology for their help systems.
>   1) User annotation.  One of the things lost when paper went away was
>      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
>      information to the local distribution of the help system can be
>      important in this type of environment (instead of saying "log
> 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
> while
>      using the product can be valuable, since they may take it into
> that
>      the developers and documenters did not have time to investigate.
>   4) Reducing development costs.  If you can get the users to write
> own
>      documentation (or part of it) you don't have to provide as much
> to
>      do it.
> The first two items have been handled by various technological
> to
> delivery engines over the years, but there is no uniform approach to
> 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
> 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
> by
> aggregation instead of planned development can become quite
> Even
> if search is the primary access method, how do you tell which entry is
> one that is most important for you, and how do you search effectively
> you
> are new to the domain and don't know the vocabulary yet (a big
> of
> indexes over full text search is that a good index teaches you the
> 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
> 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
> the tech industry, it cannot be ignored as a possible explanation.
> I am sure there are others (including "Wikis are the new buzz" which
> 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
> 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
> 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
> available in conventional channels?
> I've found one article with the nice comment from Mick Davidson
> wi
> kis/
> It seems to the user more comfortable, but for me, at author side,
> scattered. I am asking myself: If version 1.0 of product will be
> and help spread via WIKI and many users will add there their comments
> responsible persons on other side give them responses in form of
> what will happen with all this messages when version 2.0 of the
> 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
> version of documentation more clear and user friendly...
> I see in the background system like docbook. Is docbook still the
> choice? Or will be these wikis created directly without any other
> I already understand to some recent needs for DocBook-Wiki round-trip.
> 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:

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

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]