This document follows up on the proposal for a best practices document approved by the DITA Help Subcommitee (hereafter DHSC) on June 5, 2008 and updated on June 26. The general notion here is that our subcommittee has devoted time to reviewing the current options for developing Help in DITA. Until we can develop Help specializations for DITA 1.3, these options are the only things that DITA-based organizations can implement, short of developing something new from scratch. We would be doing the DITA community in general a service by summarizing our findings and providing links to relevant Help-oriented resources.
I propose that we keep things pretty simple. If we can develop one DITA topic per content area, I can pull these together into something buildable and reviewable pretty quickly. Following the general shape of the demos that we had over the past few months, here's what I would propose for a starting outline.
Section | Topic | Contributor |
---|---|---|
Introduction |
Introduction | Tony Self (HyperWrite) Stan Doherty (Individual) |
Developing DITA-based Help for Existing Help Environments |
Introduction |
Volunteer??? Stan Doherty (Individual)? |
- |
EclipseHelp |
Jeff Antley (IBM) |
- |
CSHelp Plug-in |
Jeff Antley (IBM) |
- |
AIRHelp |
Scott Prentice (Individual) |
- |
PTC Help |
Chris Goolsby (PTC) Dan Cunningham (PTC)? |
- |
HTMLHelp |
Deborah Pickett (Moldflow) |
- |
WinANT outputs and optins |
Tony Self (HyperWrite) |
Developing Custom DITA-based Help Systems |
Introduction Need matrix of options/choices. |
Stan Doherty (Individual) |
- |
WinANT context ID management |
Tony Self (HyperWrite) |
- |
TOCJS plugin |
Stan Doherty (Individual) |
- |
HTMLSearch plugin |
Stan Doherty (Individual) |
- |
XHTML (DITA-OT) |
Stan Doherty (Individual) |
- |
CSHelp Plug-in |
Jeff Antley (IBM) |
- |
Dynamically-rendered HTML |
Tony Self (HyperWrite) |
- |
VistaHelp-style expandable content |
Tony Self (HyperWrite) |
Using DITA Source with Existing HATs |
Introduction |
TBD??? |
- |
MadCap Flare |
TBD??? |
- |
RoboHelp |
TBD??? |
Resources and Demos |
Resources |
Joe Welinske |
- |
Demos (links) |
Joe Welinske |
Futures? |
Introduction |
Tony Self (HyperWrite) ? |
At the risk of sounding "pushy," I'd recommend that we start with a generic DITA topic that has a common set of headings. If writers need to rearrange them or delte them, fine ... but at least we'd be starting from a common set of items to discuss. Obviously, where there is existing documentation for a plugin or tool, we point off to it ... where there is little or no documentation, we may need to do a little writing.
Here's my take on some common <section> headings to start with.
Stan Doherty