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: RE: [dita-help] DHTG Reorganization ...

Thanks, Scott, for the thorough review of the DHTG. Sorry it’s taken so long to add my views to the subject.



I agree with you thoughts on the Introduction, and in particular with your view that we should include a statement of the criteria by which technologies are mentioned in the guide. That criteria would not only help us decide whether to mention tools such as CHM2Web, but also with providing a defensible rationale for why some tools are mentioned and others not. And it would help us avoid “scope-creep”.


Rather than have a topic that lists or references other tools (such as CHM2Web), perhaps we could reference some of the existing DITA tools lists, such as the one at the DITA Users site (http://www.ditausers.org/tools/).


DITA and User Assistance

I’m not averse to the idea of merging those topics into the introduction.


Developing for Existing Environments

I like your idea to rename this as “Help Delivery Technologies”. And for there to be one topic per Help technology, starting with a description of the format. The DMP format should be included here, as it is a Help delivery option that is specific to a particular tool. However, on deeper reflection, there are some issues with this approach. Firstly, this would leave the document structure too flat, because we’d be left with only one chapter: Help Delivery Technologies.


For tools that help you produce different types of Help output from DITA, such as RoboHelp or Flare, we end up with a dilemma. With the Help Delivery (output type) focus, it would be hard to avoid repeated mentions of tools, such as in the following structure (this is a sub-set of your structure, Scott):


Help Delivery Technologies

-          AIR-based Help

o   RoboHelp

o   Leximation tool

o   Flare

-          Browser-based Help

o   RoboHelp

o   Flare

o   tocsbis Plug-in

-          Microsoft HTML Help

o   RoboHelp

o   Flare


I think this is ungainly, and encourages repetition. Your idea of having detailed and “lightweight” topics for each has some merit. (This whole approach also seems to entail more work than a simpler tidy-up!) I think it is also a structure that seems to “demand” that all tools be listed. The alternative to the output type focus would be the tool focus, where the structure might be:


Using Help Authoring Tools to Process DITA

-          RoboHelp

o   Importing DITA

o   Generating AIR-based Help, Browser-based Help and Microsoft HTML Help

-          Flare

o   Importing DITA

o   Generating AIR-based Help, Browser-based Help and Microsoft HTML Help

Using DITA OT and Plug-ins

-          Eclipse Help

-          Microsoft HTML Help

-          Browser-based Help (through plug-ins)


There’s still some repetition, but I think this is less onerous. It would be also easier to, say, detail how to import into a “typical” HAT, using RH as an example, and mention that it is also possible to do the same things with other tools (and refer readers to their own HAT documentation). But going back and comparing this with the current structure, it’s starting to look the same. Maybe this is a good thing? Does anyone else have thoughts on the matter?


Further Reading and Resources for DITA Help

I agree that “References” or “DITA Help References” would be more succinct.















From: Scott Prentice [mailto:sp@leximation.com]
Sent: Tuesday, 14 July 2009 4:58 AM
To: dita-help@lists.oasis-open.org
Subject: [dita-help] 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 ..

    Editorial Preface
    DITA and User Assistance
    Definition of DITA Help
    Document History
Help Delivery Technologies
    Adobe AIR-based Help
        Leximation AIR Help OT Plug-in
        <<.. others>>
    Browser-based Help
        <<RoboHelp>> (include "Converting DITA Content to WebHelp using RoboHelp" ??)
        <<PTC DMP?>>
        <<.. others>>
    Eclipse Help (use the other "Eclipse Help" topic as the overview?)
            CSHelp Plug-in
            Eclipse_CSH Plug-in for Dynamic Context-Sensitive Help
        <<.. others>>
    Java Help
        <<.. others>>
    Microsoft HTML Help
            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
<<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
    <<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.



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