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] definition of Help


I don't think we're having particular trouble nailing down a definition. Such nits and adjustments are normal when folks undertake to define anything in a committee. And even if it were more difficult to define in committee than, say, umbrella stands or bookbinding, that difficulty really says absolutely nothing about whether or not it is pertinent and useful to us to define it.
 
The action item says simply "Definition of Help". Tony, you refer to it more specifically as "definition of DITA online Help". The only thing that distinguishes DITA online Help from the general case is that it is rendered from DITA sources. That's about all we can say. Granted, that delimits the scope of our problems and tasks as a SC. Assuming that DITA adopters know what they want in a Help system, our task is to enable them to render that desired output from DITA sources. If the objection being raised is that it would be kind of pointless to say this, I agree.
 
The usefulness of a definition of online Help generically (i.e. regardless of the source) is that it specifies essential and typical characteristics of that desired output instead of just assuming that everybody knows what a Help system isOur tasks can then be grouped under the various essential or typical characteristics. If we subsequently identify a problem (and its associated committee tasks) for which none of these headings fit, we've identified some additional characteristic of our objective.
 
Version 3 of a definition follows. I changed "Optional characteristics" to "Typical characteristics". That removes an equivocation on the word "optional". In-topic links, ToC, and Index are optional, but if present it is essential that they provide links to topics.  The other characteristics are typical but not essential (and therefore implicitly optional). I also hedged in-topic links with "if provided", as requested. (I always put them in, so that possibility didn't occur to me. DITA puts them in if you specify reltable, but best practices say don't put them in otherwise. An interesting mixed bag.)
_______________________________________________________
 
What is Online Help?
 
Essential characteristics:
* It is user-assistance documentation.
* It is presented by a computer.
* Each topic is presented separately. (Like a website.)
* In-topic links, if provided, support navigation to other topics. (Like a website.)
* A ToC, if provided, links to topics. (Unlike that in a book.)
* An Index, if provided, links to topics. (Unlike that in a book.)
 
Typical characteristics:
* It documents a software product.
* It is integrated with the UI of that product.
* Parts of the UI may be linked to topics written about them (embedded Help).
* Procedural steps may be linked to parts of the UI used to execute them (online coach).
* It may have ToC, index, search, or other means of identifying THE relevant bit of content.
* It may have ToC, radial tree, mind-map, or other graph representation mapping a subject-matter domain.
 
Ancillary considerations:
* The location of the Help topic content (e.g. local disk, website, cloud) is immaterial.
* The delivery mechanism (e.g. HTML browser, CHM viewer, PDF viewer) is immaterial.
* The type of display (e.g. CLI, GUI, kiosk, audio, video, mixed media) may constrain the types, format, and other characteristics of the content.
 
 


From: Goolsby, Chris [mailto:cgoolsby@ptc.com]
Sent: Monday, January 24, 2011 8:56 AM
To: Scott Prentice; tself@hyperwrite.com
Cc: dita-adoption-help@lists.oasis-open.org
Subject: RE: [dita-adoption-help] definition of Help

Given the trouble we are having nailing down a definition of online help, I would tend to agree with Scott that it might not be needed. I think anybody who goes through the trouble to find and read our guide will already have a good notion of what *they* think “online help” means.

 

Regards.

 

Chris

 

From: Scott Prentice [mailto:sp10@leximation.com]
Sent: Monday, January 24, 2011 1:30 AM
To: <tself@hyperwrite.com>
Cc: <dita-adoption-help@lists.oasis-open.org>
Subject: Re: [dita-adoption-help] definition of Help

 

Hi Tony...

 

Yes .. I knew *why* we were talking about it, I was just throwing out the idea that maybe it wasn't needed. If you all think it's useful to include, that's fine with me. 

 

Cheers,

...scott


On Jan 23, 2011, at 7:16 PM, "Tony Self" <tself@hyperwrite.com> wrote:

Hi Scott

 

We’re talking about a definition because the DHTG topic list (http://wiki.oasis-open.org/dita-adoption/DITA_Help_Technologies_Guide_Allocation) has a topic called “Definition of DITA Help” assigned to Bruce.

 

I think it would be useful so that readers know whether the DHTG might apply to them.

 

Tony

 

 

From: Scott Prentice [mailto:sp10@leximation.com]
Sent: Monday, 24 January 2011 11:10 AM
To: <tself@hyperwrite.com>
Cc: <dita-adoption-help@lists.oasis-open.org>
Subject: Re: [dita-adoption-help] definition of Help

 

Hi All...

 

I may be off base here, but .. why are we defining "Online Help"? Who are we to define this? It seems that online Help is whatever the person creating the Help decides that it is. In my mind, online Help is anything from a single "screen" of text to a complex hyperlinked, multi-topic, context sensitive, fully featured (toc, search, index, bookmarks, commenting enabled, etc.)  assembly of content. It could be sourced from a text file, HTML, XML, PDF, or other yet to be invented content delivery method. It may be contain textual content, images, videos, audio recordings .. one, some, or all of these information delivery methods. 

 

This is an interesting task, but after thinking about it a bit, I guess I'm not sure what the benefit is for us to make this definition. To me, online Help is really just .. information presented to an end user through a computer interface intended to assist in accomplishing a task. 

 

I'm fine with including a definition if y'all think it's going to be useful to the readers of the DHTG, but I just thought I'd share my thoughts. 

 

Cheers!


...scott


On Jan 23, 2011, at 3:07 PM, "Tony Self" <tself@hyperwrite.com> wrote:

Greetings colleagues

 

I think we might have gotten off track here a little.

 

In defining what Online Help is, Bruce suggested:

 

>> 

What is Online Help?

 

Essential characteristics:

  • It is user-assistance documentation.
  • It is presented by a computer.
  • Each topic is presented separately. (Like a website.)
  • In-topic links support navigation to other topics. (Like a website.)
  • A ToC, if provided, links to topics. (Unlike that in a book.)
  • An Index, if provided, links to topics. (Unlike that in a book.)

 

Optional characteristics:

  • It documents a software product.
  • It is integrated with the UI of that product.
  • Parts of the UI may be linked to topics written about them. (Embedded help.)
  • Procedural steps may be linked to parts of the UI used to execute them. (Online coach.)

 

Ancillary considerations:

  • The location of the content (e.g. local disk, website, cloud) is immaterial.
  • The type of display (e.g. CLI, GUI, kiosk, audio, video, mixed media) may constrain the content.

<< 

 

Should we add Search to the “Essential Characteristics”, after the mentions of TOC and Index. My feeling is that it would be difficult to add search at this point, because it is not essential, and it doesn’t have different behaviour to any other form of content.

 

I do think that the fourth point, “In-topic links support navigation...” should be changed to “In-topic links, if provided, support navigation...” or else leave it out. (My point is that in-topic links aren’t really essential... I encounter quite a few help systems that rely on the TOC for inter-topic navigation.)

 

Tony

 

 

 

 

 

 

 

 

 

From: ian balanza-davis [mailto:ibalanza_davis@yahoo.co.uk]
Sent: Saturday, 22 January 2011 8:16 AM
To: Bruce Nevin (bnevin); cgoolsby@ptc.com; dita-adoption-help@lists.oasis-open.org
Subject: Re: [dita-adoption-help] definition of Help

 

Defining help authoring, yes. But searching is essentially a user-driven exercise rather than an author-guided one. And if you try to address search as part this topic I think you would be limited to explaining how to use search including wild cards, quoted strings, and the like.

There could be as many different answers to that as there are online help systems, and describing search usage should really be the job of whatever "how to use this system" goes with the specific form of help.

I agree the concept of searching should be explained. But it may, like TOC and index, be more appropriate to describe it as a key feature of a help system, whatever format that system takes.






From: Bruce Nevin (bnevin) <bnevin@cisco.com>
To: ian balanza-davis <ibalanza_davis@yahoo.co.uk>; cgoolsby@ptc.com; dita-adoption-help@lists.oasis-open.org
Sent: Fri, 21 January, 2011 20:15:23
Subject: RE: [dita-adoption-help] definition of Help

Just for clarification, why? Are we defining Help authoring? 

> -----Original Message-----
> From: ian balanza-davis [mailto:ibalanza_davis@yahoo.co.uk]
> Sent: Friday, January 21, 2011 2:58 PM
> To: Bruce Nevin (bnevin); cgoolsby@ptc.com;
> dita-adoption-help@lists.oasis-open.org
> Subject: RE: [dita-adoption-help] definition of Help
>
> I think in all these cases, we would be best sticking to
> navigation elements authors have control over.  I am not sure
> search falls into that -- at least not without becoming an index.
>
> On Fri, 21 Jan 2011 19:36 GMT Bruce Nevin (bnevin) wrote:
>
> >Right! And also not unique to Help.
> >
> >More generally, these are all means for identifying THE
> relevant bit of
> >content and presenting it, and any other such means that can be
> >imagined and implemented can be "optional characteristics" of Help.
> >That rather vitiates the notion "optional characteristic". Google's
> >search algorithms (and underlying them their intensive statistical
> >analyses of huge bodies of content) would be very Helpful.
> >
> >The ToC can in addition be a high-level overview of the
> structure of a
> >subject matter. Other presentations, such as a radial tree or a
> >'mind-map' sort of graph can also serve this function.
> >
> >
> >________________________________
> >
> >    From: Goolsby, Chris [mailto:cgoolsby@ptc.com]
> >    Sent: Friday, January 21, 2011 2:12 PM
> >    To: Bruce Nevin (bnevin);
> >dita-adoption-help@lists.oasis-open.org
> >    Subject: RE: [dita-adoption-help] definition of Help
> >   
> >   
> >
> >    Do we want to address search at all? You talk about ToC
> and Index.
> >Maybe search is an optional characteristic?
> >
> >   
> >
> >    Chris Goolsby
> >
> >    PTC-Arbortext
> >
> >   
> >
> >    From: Bruce Nevin (bnevin) [mailto:bnevin@cisco.com]
> >    Sent: Friday, January 21, 2011 12:47 PM
> >    To: dita-adoption-help@lists.oasis-open.org
> >    Subject: RE: [dita-adoption-help] definition of Help
> >
> >   
> >
> >    Right, modular is an ambiguous term, and inspecific.
> >
> >        >> May help with a user domain separate from
> its software vehicle.<<
> >
> >        Do you mean that Online Help doesn't have to be
> associated with a
> >piece of software? Or do you mean that some content in a software's
> >Help might describe indirectly-associated concepts, business
> rules and
> >the like?
> >
> >    I meant the latter, e.g. a museum exhibit. Guidance for
> conflict of
> >interest, insider trading, and the like might be examples of
> business
> >rules. I'm sure you had other examples in mind, what are they?
> >
> >   
> >
> >    Here's another take which I think addresses your points.
> >
> >    _____________________________________________________________
> >
> >   
> >
> >    What is Online Help?
> >
> >   
> >
> >    Essential characteristics:
> >
> >    *    It is user-assistance documentation.
> >    *    It is presented by a computer.
> >    *    Each topic is presented separately. (Like a website.)
> >    *    In-topic links support navigation to other topics. (Like
> >a website.)
> >    *    A ToC, if provided, links to topics. (Unlike that in a
> >book.)
> >    *    An Index, if provided, links to topics. (Unlike that in
> >a book.)
> >
> >   
> >
> >    Optional characteristics:
> >
> >    *    It documents a software product.
> >    *    It is integrated with the UI of that product.
> >    *    Parts of the UI may be linked to topics written about
> >them. (Embedded help.)
> >    *    Procedural steps may be linked to parts of the UI used
> >to execute them. (Online coach.)
> >
> >   
> >
> >    Ancillary considerations:
> >
> >    *    The location of the content (e.g. local disk, website,
> >cloud) is immaterial.
> >    *    The type of display (e.g. CLI, GUI, kiosk, audio, video,
> >mixed media) may constrain the content.
> >
> >       
> >
> >________________________________
> >
> >        From: Tony Self [mailto:tself@hyperwrite.com]
> >        Sent: Thursday, January 20, 2011 8:44 PM
> >        To: Bruce Nevin (bnevin);
> >dita-adoption-help@lists.oasis-open.org
> >        Subject: RE: [dita-adoption-help] definition of Help
> >
> >        Hi Bruce
> >
> >       
> >
> >        Here are some thoughts.
> >
> >       
> >
> >        >> Modular--relatively short topics<<
> >
> >        Modular might not be the right term to use,
> because "modular Help" is
> >used commonly to describe multiple Help systems that are merged at
> >runtime to be delivered as a virtual single Help system.
> >
> >       
> >
> >        >> May help with a user domain separate from
> its software vehicle.<<
> >
> >        Do you mean that Online Help doesn't have to be
> associated with a
> >piece of software? Or do you mean that some content in a software's
> >Help might describe indirectly-associated concepts, business
> rules and
> >the like?
> >
> >       
> >
> >        I think we also need to define "online".
> >
> >       
> >
> >        Regards
> >
> >       
> >
> >        Tony Self
> >
> >       
> >
> >        From: Bruce Nevin (bnevin) [mailto:bnevin@cisco.com]
> >        Sent: Friday, 21 January 2011 8:43 AM
> >        To: dita-adoption-help@lists.oasis-open.org
> >        Subject: [dita-adoption-help] definition of Help
> >
> >       
> >
> >        I see
> >http://wiki.oasis-open.org/dita-adoption/DITA_Help_Technologi
> es_Guide_A
> >l
> >location
> ><http://wiki.oasis-open.org/dita-adoption/DITA_Help_Technolog
> ies_Guide_
> >A
> >llocation>  that I am on the hook for a definition of Help. Here's a
> >quick draft for comment.
> >
> >       
> >
> >       
> >
> >        What is Online Help?
> >
> >        *    User assistance documentation.
> >        *    Modular--relatively short topics, in some forms
> >(e.g. rollover) smaller than a topic.
> >        *    Delivered online by software, either locally or
> >on the web.
> >        *    Usually integrated with the UI of the software
> >that it documents.
> >
> >            *    May help with a user domain separate
> >from its software vehicle.
> >            *    Is a kiosk or a guide to an exhibit
> >online Help?
> >
> >        *    May be context sensitive (linked to user action
> >or location or the state of the application).
> >
> >        These characteristics usually compel the Help
> developer to address
> >the problem of relevance that is central to all
> >documentation: access to the relevant topic from the context of need.
> >
> >       
> >
> >        All user assistance documentation is part of
> the user interface; a
> >Help system only more obviously so.
> >
> >            /B
> >
>
>
>
>     
>
> ---------------------------------------------------------------------
> 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]