Re: Open Source Help Viewer ( was Re: I'm sticking with WinHelp (wasRe: WinHelp on Vista - a

[Sean Wheller <sean -at- inwords -dot- co -dot- za>]

On Saturday 07 October 2006 03:12, sbuckley wrote:
> I totally agree.  I also have a few questions.
>
> I've mostly written for systems used in one platform (Windows or Unix) and
> have had issues getting dev to agree to ship a control, little alone a
> viewer, with software.  When you have worked with Linux, was it just "work
> as normal" to ship the viewer and, if not, how did you overcome those
> issues?

In the case of a GNU/Linux-based distros running either KDE or GNOME desktop 
graphical environments there is not much of a problem. Reason is that both 
desktop environments provide a method by which to access help. In KDE this is 
the KHelpCenter and in GNOME this is the Yelp Viewer. So the need to package 
and ship a help viewer has already been obviated. However, does not exclude 
shipping ones own, as with FireFox and OpenOffice.org.

Interestingly the KDE and GNOME viewers are not designed to display only one 
format. They already provide support for viewing multiple formats and are 
being extended to support more. Where Microsoft goes wrong is that they 
always provide a help viewer that is designed to display a single help 
format. One that imposes their perspective on how help should be displayed 
and in what format. Many, myself included, feel that this restricts a help 
developers ability to design a help system that is suited to user 
requirements.

Still the problem with help viewers on KDE and Yelp is that there are still 
two help viewers (KHelpCenter and Yelp), each with its own ideas on how to 
implement help that sometimes induce incompatibilities. Hopefully work at the 
freedesktop project [http://www.freedesktop.org] will result in better 
interoperability between the help viewers as it has with other projects.

So the answer in shipping help for GNU/Linux-based systems, other than 
shipping your own viewer, is presently to ship a doc package that will 
install in the central location for documentation and integrate with the 
existing help viewer environment. Which format you decide to ship is 
dependent on whether or not the help viewer supports that format. Most will 
support man pages, info pages, tex, html, xhtml, pdf. Where Yelp is different 
is that it reads directly from Docbook XML. As it does this, it transforms 
the XML into HTML. This functionality is not available in KHelpCenter. There 
are pros and cons to this approach. 

>
> I've also wondered if an authoring environment standard is not also needed.
> I've started to look at XML standards.  I've worked with XML in the past.
> Since anything was possible I saw teams go a bit nuts and the result was a
> bit messy.  Lately I've been looking at XML authoring standards like DITA.
> Have you worked with such authoring standards in the past and would they
> also be part of the plan?

The defacto standard for storing documentation on GNU/Linux-based systems is 
DocBook XML. Most projects use DocBook, but are not limited to DocBook. So it 
does not exclude the use of DITA as an option in the future. The open source 
community will, I believe is, considering the use of any open, 
standards-based technology. So, I am sure we will see the inclusion of 
documentation, built using DITA, into GNU/Linux-based distributions very 
soon. However, at present there is an enormous amount of DocBook legacy and 
new Documents are being added in DocBook XML everyday. In the event that DITA 
should come to the fore, I do not think the open source help viewers would no 
longer provide support for older format types.

From our perspective (InWords), we have a position to be "the open 
documentation company". As such we choose to use free, open source and 
standards-based technologies as much as possible when developing 
documentation. Our main approach is to use a completely free, open and 
standards-based technology stack. For this reason, we will even apply this 
principle when building documentation for Windows-based systems. I know, it 
sounds strange to think that a person will use a GNU/Linux-based desktop and 
toolchain to develop documentation and help systems for Windows, but we have 
and do. We simply run Windows on Linux :-) So our main development 
environment is in the Linux world based on DocBook XML, and our testing or 
reference environment is in Windows. Having said this, we do not stipulate 
that a person cannot develop documentation using Windows, Mac OS, Solaris, 
etc. and therefore have accommodated this freedom of choice by building our 
documentation toolchain on open source technologies that are portable across 
platforms.

When we write documentation, we do not have to write for the specific help 
viewer or platform. We just write about the product and transform our DocBook 
sources to support the requirements of the target platform, target format, 
target audience, target customer, etc.

The important point here that both DocBook and DITA provide open and 
standards-based formats. Both are based on the principle of "separation of 
concerns" - manuscript and presentation are separate issues, managed in 
separate space and time. When you transform to a presentational instance, it 
is one format in many spaces and one version in time. It is only used for the 
purpose of viewing. If you wish to update, then go back to the source which 
embodies space and time in a single instance.

Selecting to store documentation in an open and standards-based format that is 
sans any presentational detail is, in my opinion, the most important 
consideration for any documentation department.

For the first step it means that documentation sources are not locked into any 
single editor or viewer application.  Comparing this with the past, tools 
such as RoboHelp, ForeHelp, AuthorIT can no longer be considered 
single-source for the reason that they all stored documents in a manner that 
would not make the format openly exchangeable between editing environments. I 
am sure many of us have encountered situations where we need to provide or 
receive documentation from another company, a technology partner perhaps, but 
do not have the same tools.

I think most companies are now recognizing that this level of vendor lock-in 
is unacceptable and not in the customers interest. Hence we see people like 
MadCap embracing open and standards-based formats. An approach that I think 
is very wise and that will ultimately win them many customers. Not only 
because of the the features and functions they ship, but also because 
customers can be relatively assured that they are not locked into the Flare 
product. Of course, should Flare produce a format that is not easily 
exchangeable across editing environments, then they may as well join the 
ranks of RoboHelp, ForeHelp and AuthorIT.

Providing an open, standards-based, format and authoring environment that 
embraces them will be a must for any authoring tool vendor in the future and 
a distinct competitive advantage while other authoring tool vendors do not do 
so. It also means that open source is going to be a very bug factor in the 
future of technical documentation development.

In discussing how to create an "Open Source Help Viewer". I think that a Help 
Viewer should be cross-platform and capable of displaying numerous formats.

Whew!! Hope this helps.

-- 
Ask me about the Monkey.

Sean Wheller
Technical Author
sean -at- inwords -dot- co -dot- za
+27-84-854-9408
http://www.inwords.co.za
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content
delivery. Try it today! http://www.webworks.com/techwr-l

Easily create HTML or Microsoft Word content and convert to any popular Help file format or printed documentation. Learn more at http://www.DocToHelp.com/TechwrlList

---
You are currently subscribed to TECHWR-L as archive -at- infoinfocus -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%40infoinfocus.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to lisa -at- techwr-l -dot- com -dot-  Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.