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

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita-adoption-help message

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


Subject: Re: [dita-adoption-help] Criteria for determining which tools toinclude in the DHTG...


I think it's hard to differentiate between an online document that's a 
"Help" file (as Bruce describes it) vs. one that's more of an online 
book (or "just content"). It seems like it really comes down to how it's 
used by the end user. I have a WinHelp file that I created many years 
ago from the FrameMaker documents that were provided by the developer. 
This is a programmers language reference from which I created a Help 
file .. it's not connected to any application, but I use it as "Help" 
(although you could consider that I'm doing the same thing that I would 
do if it was a printed book). I'm able to quickly locate the function 
description I'm interested in and get the relevant information then get 
back to my work (the context hook is me). Is this Help or is it an 
online book?

For me, I think of Help as being something that you don't read in a 
linear fashion. You jump in to a specific topic, get the info you need 
and leave. You might read a section (many topics) to get an over all 
concept, but you're not likely to read the whole thing from start to 
finish like a book. But .. you could. Even the most Help-ish 
hyperlinked, context driven Help system, could probably be read like a 
book if someone wanted to do so (unless they don't provide a TOC, which 
is becoming the fashion .. something that I find completely abhorrent).

I have a feeling that you could take any digital content delivery format 
and make it highly contextual and linked to the product that it supports 
.. that includes PDF and ePub .. and any other digital format you can 
name. Whether it's a good idea to do that probably shouldn't be up to us 
to decide.

I guess I'm coming to the opinion that we should include both of those 
formats in the DHTG, but we should indicate that they may not be a 
considered a typical "Help" format. We don't need to go into great 
detail and should not provide information on how to create these files, 
but rather reference other documentation that covers the subject. I 
don't think this will open up a can of worms or complicate things in any 
way .. it will just make the DHTG more complete.

Any digital file format that can be generated from DITA and provides 
some form of user assistance should probably be included in the DHTG.

...scott


Bruce Nevin (bnevin) wrote:
> OK. I'm glad to be corrected about PDF.
>  
> But I gather you have no disagreement with the first paragraph. Help 
> is not just content, it is delivery of the particular content that is 
> relevant to a problem that arises during use of whatever it is that 
> the help system documents. It is distinguished by identifiers of 
> relevance and modes of access to relevant content over and above those 
> found in other modes of publication (i.e. in addition to the ToC and 
> index that are found in both books and help systems).
>  
>     /B
>
>     ------------------------------------------------------------------------
>     *From:* ian balanza-davis [mailto:ibalanza_davis@yahoo.co.uk]
>     *Sent:* Tuesday, September 28, 2010 3:06 AM
>     *To:* Bruce Nevin (bnevin)
>     *Cc:* Scott Prentice; dita-adoption-help@lists.oasis-open.org
>     *Subject:* Re: [dita-adoption-help] Criteria for determining which
>     tools to include in the DHTG...
>
>     I disagree.
>
>     Where there are issues of cross-platform application, a reluctance
>     to use active aspects of XHTML, and a lack of native support for
>     items like MathML is some browsers, PDF may seem a suitable solution.
>
>     Adobe reader allows hooks to page or ID and that can be used to
>     replicate CSH calls; links can be created between PDFs for
>     interlinked documentation sets; and ultimately PDF provides a more
>     consistent cross-platform look and feel than trying to grapple
>     with a multitude of browsers and their CSS implementations.
>
>     Yes PDF is a format for printing a document, but the functionality
>     that has been shoe-horned into it has moved it away from simply
>     that into an alternative to CHM, JavaHelp, et al; and it is used
>     in that manner.
>
>     If PDF is to be ignored, I think you need a stronger grounding
>     than simply by fiat -- you are ignoring the potential that exists
>     and also the users who find this a solution.
>
>     Ian
>
>     ------------------------------------------------------------------------
>     *From:* Bruce Nevin (bnevin) <bnevin@cisco.com>
>     *To:* Scott Prentice <sp10@leximation.com>;
>     dita-adoption-help@lists.oasis-open.org
>     *Sent:* Mon, 27 September, 2010 22:15:24
>     *Subject:* RE: [dita-adoption-help] Criteria for determining which
>     tools to include in the DHTG...
>
>     One key characteristic is that you access Help when you have a
>     problem,
>     and you locate one or more topics that are relevant to the
>     problem. Help
>     delivery, then, is mostly about relevance. Another is that Help
>     delivery
>     is carried out by an application. It is possible to search out a
>     CHM and
>     launch it as one would launch a PDF book, but then there's a strong
>     argument that you are using it as a standalone publication and not as
>     online help.
>
>     If we can assume that users expect context sensitive help integrated
>     with the application, then PDF becomes harder and harder to justify.
>
>     We could just list typical Help formats and rule out PDF by fiat.
>
>         /B
>
>     > -----Original Message-----
>     > From: Scott Prentice [mailto:sp10@leximation.com
>     <mailto:sp10@leximation.com>]
>     > Sent: Monday, September 27, 2010 3:32 PM
>     > To: dita-adoption-help@lists.oasis-open.org
>     <mailto:dita-adoption-help@lists.oasis-open.org>
>     > Subject: [dita-adoption-help] Criteria for determining which
>     > tools to include in the DHTG...
>     >
>     > Hi...
>     >
>     > This action item of mine is a bit overdue. Here's what I'm
>     > thinking should be the criteria ..
>     >
>     > - A tool can be included in the DHTG if that tool can consume
>     > or create DITA, and can export out-of-the-box, through the
>     > tool's UI, at least one "Help" format.
>     >
>     > Even if that tool is just using the OT to generate this Help
>     > format, as long as it installs the OT to do that, it can be
>     > in the DHTG. This probably opens the door to many DITA
>     > authoring tools, but excludes tools that do not themselves
>     > consume DITA in some way. It would not include a tool that
>     > just converts from one format to another, since this would
>     > have nothing to do with DITA.
>     >
>     > Then there is the issue of defining what constitutes a "Help"
>     > format. I think that for the purposes of the DHTG, a Help
>     > format is one that's described in the "Help Delivery
>     > Technologies" section of the DHTG. How we decide what to put
>     > in that section .. well, I suppose that's up for discussion.
>     > There are two formats that I can see might be considered "on
>     > the fence" of being a Help format or not .. PDF and ePub.
>     > There are people who use PDF as the "online Help system," and
>     > therefore this would be considered a Help format (I'd think)
>     > .. even though I personally think this is a bad use of PDF.
>     > But what about ePub? What exactly does make something a Help format?
>     >
>     > Something for further discussion, I'd think.
>     >
>     > Cheers,
>     >
>     > ...scott
>     >
>     >
>     >
>     ---------------------------------------------------------------------
>     > To unsubscribe from this mail list, you must leave the OASIS
>     > TC that generates this mail.  Follow this link to all your
>     > TCs in OASIS at:
>     > https://www.oasis-open.org/apps/org/workgroup/portal/my_workgr
>     > oups.php
>     >
>     >
>
>     ---------------------------------------------------------------------
>     To unsubscribe from this mail list, you must leave the OASIS TC that
>     generates this mail.  Follow this link to all your TCs in OASIS at:
>     https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
>
>


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