Thanks, Scott, for the thorough review of the DHTG. Sorry it’s
taken so long to add my views to the subject.
Introduction
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
o DITA
OT
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.
Cheers
Tony
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 ..
----------------------------------
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