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


Stan Doherty