[INTERNAL] DHSC Best Practices Proposal

This document describes the general contents for the proposed Best Practices Guide for Authoring Help in DITA.

Overview

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.

Proposed Contents and Contributors

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

Topic Structure

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.

Overview: discussion of what the plug-in or tool does (features) and why someone might want to use it
Setup and configuration: where to download or purchase it, how to install (high-level) it, and how to configure it (high-level)
Authoring: what to do (if anything) in DITA source files to take advantage of the plugin or tool
Integration: what does someone do to integrate this plugin or tool with an engineering environment (context IDs at a minimum)
Output: screen shots or links to live output
Summary: final comments, evelautaions, recommendations

Stan Doherty