DHTG Reorganization ...

Hi All...

I've finally started taking a look at the DHTG with regard to some of
the concerns expressed by others. I'm assuming that this document will
always be a work in progress as new technologies are developed and the
DITA specification is augmented to support more Help-specific features.
We've got a lot of good content, but the organization of that content
could be streamlined and organized in a more consistent manner. I'll
walk through the document and propose some suggestions/questions. Keep in mind
that these suggestions are just a starting point .. perhaps we can talk
about this in detail at an upcoming meeting.

Introduction .. this all seems good, although some of this seems
more like it would be in a pre-intro frontmatter type of stuff
(specifically the Contributors and Doc History). Also, I think that we
need to also have a topic that specifically defines what type of
technologies are to be discussed. We start to talk about it, but I'm
thinking that to avoid problems in the future we should define specific
requirements for tools and technologies. Such as .. for a specific tool
to be "featured" it must in some way relate to DITA. A suggestion was
made to have a topic on the CHM2Web conversion tool .. this tool has
absolutely nothing to do with DITA. It may be a great conversion
utility and could be used in a DITA-sourced pipeline, but if we include
a topic explaining how to use this, we open ourselves up to include
hundreds of other non-DITA (but very useful) tools. Perhaps there
should be a single topic that includes references to these useful
tools, but they don't belong in the TOC. Also since this document
focuses on Help technologies we should probably not include discussions
of authoring tools unless a particular tool provides Help-specific
features. It is assumed that all authoring tools can pass a file to the
OT (or other Help creation utility), so this wouldn't quality. 

DITA and User Assistance .. should these topics get merged into
the Intro?

Developing DITA-based Help for Existing Help Environments ..
this is a bit of a mouthful, and seems unnecessarily specific. How
about we change this to something simpler like .. Help Delivery
Technologies .. ? Within this "chapter" would be a topic for each Help
technology that can be generated from DITA (making sure to include the
company name if appropriate) ..

Help Delivery Technologies

- Adobe AIR-based Help

- Browser-based Help

- Eclipse Help

- Java Help

- Microsoft HTML Help

- PTC Arbortext Digital Media Publisher

Each of these topics should start with a general description of the
"format" then include sub-topics for implementation options. Right now
the structure of these sections is not very consistent and in many
cases, the general description is either missing or could be beefed up
a bit. We should assume that people may use this document as a way to
decide on an appropriate Help delivery format, so need to be sure to
provide the basics.

One problem I'm having is that there are tools that can create multiple
types of Help output from DITA. At the most basic level, the OT would
be listed under each of these top-level topics. This may be a nice
"basic" topic for each deliverable. But then there are tools like
RoboHelp and Flare, that can generate most of these outputs from DITA
.. do we provide a topic under each output type that says how to get
that format? Then there's PTC's DMP .. from what I understand (which is
very little in this regard), DMP *is* a help delivery option, but it's
also a tool for creating Browser-based Help.

I'm wondering if we should have another "chapter" called "Help
Development Tools" where we can provide the gory details of a tool,
then reference those from lightweight topics in the "Help Delivery
Technologies" section? These lightweight topics would just provide info
about the tool and how it relates to the output format.

Developing Custom DITA-based Help Systems .. this chapter really
applies to most of the Help output formats, but only if they were
generated through the OT (is this correct?). I'm thinking that the OT
should just be considered another "tool" and this information might all
be included under the .. Help Development
Tools > DITA Open Toolkit .. topic.

Developing DITA-based Help for Existing Help Authoring Tools ..
this heading is also a bit of a mouthful. Would this information be
moved to the "tools" section?

Further Reading and Resources for DITA Help .. in the effort to
streamline, perhaps this could be just called "Resources"?

Here's a stab at a reorganization of the TOC ..

----------------------------------

Introduction

    Editorial Preface

    DITA and User Assistance

    Definition of DITA Help

    Contributors

    Document History

    

Help Delivery Technologies

    Adobe AIR-based Help

        Leximation AIR Help OT Plug-in

        <<RoboHelp>>

        <<Flare>>

        <<.. others>>

    Browser-based Help

        <<OT>>

        <<RoboHelp>> (include "Converting DITA Content to
WebHelp using RoboHelp" ??)

        <<Flare>>

        <<PTC DMP?>>

        <<.. others>>

    Eclipse Help (use the other "Eclipse Help" topic as the overview?)

        <<OT>>

            CSHelp Plug-in

            Eclipse_CSH Plug-in for Dynamic Context-Sensitive Help

        <<.. others>>

    Java Help

        <<OT>>

        <<.. others>>

    Microsoft HTML Help

        <<OT>

            Context-Sensitive Help Using the Enhanced HTML (htmlhelp2)
Plug-In

            Context-Sensitive HTML Help Using the The DITA Open Toolkit

        <<.. others>>

    PTC Arbortext Digital Media Publisher

        <<OT??>>

    

<<Help Development Tools>> (include "Developing DITA-based
Help for Existing Help Authoring Tools")

    <<OT>> (was "Developing Custom DITA-based Help Systems")

        DHTML Effects in HTML Generated from DITA

        DITA-OT Plug-ins

            HTMLSearch Plug-in

            TOCJS and TOCJSBIS Plug-ins

        Dynamic Rendering of DITA into XHTML

        JavaScript-Based Context Sensitive Help

        WinANT Options Supporting HTML-Based Output

        WinANT Options Supporting Microsoft HTML Help 

    <<RoboHelp>

    <<Flare>>

    <<PTC Arbortext Digital Media Publisher>>

    <<.. others>>

    <<Useful Utilities>> (include info about other related
conversion tools .. like CHM2Web)

Resources (was "Further Reading and Resources for DITA Help")

----------------------------------

Remember .. I'm not terribly attached to any of this, and it's just a
first stab at reorganizing things. Let me know what you think and where
I've missed the boat.

Cheers!

...scott