OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita-help message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: 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








[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]