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


Hi Tony...

And sorry for taking so long to reply to your reply. :)

See a couple comments below ..

Cheers,

...scott


Tony Self wrote:
>
> 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/).
>
SP>> I think it might be hard to find lists that provided useful and 
focused information. If we just provided a topic titled "Useful Tools" 
(or some such name) that we could add names and a very brief description 
of the benefit, we could keep adding to this list as people suggest more 
tools. That way we've provided all of the possibly useful info in one place.
>
> *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.
>
SP>> I agree that this would get repetitious, especially since the 
information in the HAT-specific topics would often be .. "read the 
documentation." I do think that it is important to provide people with a 
single path to the options for generating the type of Help that they are 
interested in, but rather than having a topic under each deliverable 
type for each HAT, perhaps we should have a topic under each deliverable 
type titled "Generating <deliverable type> with Help Authoring Tools." 
In this topic would be a list of the HATs that have options for that 
particular deliverable type with a brief description of each and a link 
to the full topic on that HAT in the "Help Development Tools" section? I 
think that most people will come at this with a focus on knowing the 
deliverable they want to provide, and wanting to know the alternative 
options, rather than knowing the tool they want to use.

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


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