4

For the web application we are currently working on, we will have to think in advance on how to roll it out to a number of different user groups. From a functional side it is important to have a documentation system in place that can be used to generate a user guide and context-sensitive help from the same source files.

We have planned to use DITA as documentation system and are now thinking about an easy and extensible way to let developers specify elements that provide context-sensitive help and can be populated by the technical writers and trainers.

Based on DITA we would like to generate a user guide in PDF and context-sensitive help integrated into a JSP-based web application. What recommendations do you have?

We are already in the process of evaluating a commercial application that has the following features

  • authoring tool to identify elements on a web page that will be populated with help information
  • integration with learning management systems
  • support for applications that are not web-based

Do you have any framework recommendations? In addition to the above, the following would be great

  • integrate with DITA (in any conceivable way)
  • user group specific content (user retrieved from web application)
  • can be used from within a simple web application to show (html) tool tips
  • association of help context with the following hierarchy: application > page > element (HTML id?)
Kariem
  • 3,366
  • 2
  • 38
  • 57
  • Did you ever come up with a solution? We are looking at doing something similar. – Beep beep Apr 25 '11 at 02:06
  • Unfortunately nothing that could be called an acceptable solution. We have popped a proprietary instruction framework on top of our application, because the customer already uses this framework for other solutions. I would not recommend this to anyone, because it raises the maintenance cost of the help system. – Kariem May 02 '11 at 22:06

1 Answers1

1

DITA is a document architecture, not a tool. So it does not constrain your choices for an authoring tool, or for producing PDF and on-line Help from your DITA source. It's not clear what sort of on-line Help you have in mind, but it sounds more like you want HTML pages that can be displayed by the application itself than a tripane like CHM.

There are several tools that will generate your outputs from DITA. The DITA-OT (Open Toolkit) is a FOSS tool on Sourceforge that can make XSL-FO, from which you can produce PDF, and also HTML, CHM, and a few more. Then there is free DITA2Go http://dita2go.com which makes Word RTF for PDF production, as well as HTML and several forms of on-line Help; it uses the topic ID attribute as part (or all, if you want) of the HTML file names. Plus there are commercial programs, though not with much of a benefit over DITA2Go.

You are best off not to think of PDF as an on-,line Help delivery format, but just as a version that customers can print out and use as hard copy. And tooltips are really up to your Web application more than a help-generating tool.

Jeremy Griffith
  • 306
  • 2
  • 7
  • Welcome to Stack Overflow! Thanks for posting your answer! Please be sure to read the [FAQ on Self-Promotion](http://stackoverflow.com/faq#promotion) carefully. Also note that it is *required* that you post a disclaimer every time you link to your own site/product. – Andrew Barber Feb 17 '13 at 04:55