[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [dita-adoption-help] definition of Help
The definition focuses on the structure of HELP content, not on how it is delivered or how it is created. It is therefore necessarily technology agnostic. It's not even inherently tied to DITA as a technology. We put it up there as a target, and then we shoot DITA at it. Along the way we will surely consider the requirements and limitations of various HATs and delivery mechanisms, but because our target is at a high level it is not limited to the technologies that are presently available. Notepad could deliver flat ASCII files, and it could be used as a sort of HAT to create them. The "if provided" hedge permits flat ASCII files. (Note that UNIX man pages have index mechanisms that link to topics.) This being possible is as irrelevant to the definition as it being unlikely and uninteresting. What is the purpose of this definition? I've proposed that its purpose is to help us to approach the problems and tasks of this subcommittee in an orderly way. That proposal was as follows: > ... it specifies essential and typical characteristics > of [the user's] desired output instead of just assuming > that everybody knows what a Help system is. Our 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. Is this incorrect? What are the purposes for the reader? My guess is that the reader doesn't care and won't find a high-level technology-agnostic definition of Help useful, and the relevance to the user will be in the fruit it bears, the results of orienting our work within a definition of our proper domain. /B > -----Original Message----- > From: Scott Prentice [mailto:sp10@leximation.com] > Sent: Monday, January 24, 2011 12:26 PM > To: dita-adoption-help@lists.oasis-open.org > Subject: Re: [dita-adoption-help] definition of Help > > Sorry .. just me making more trouble. :o > > Is this a definition of a "Help technology" or an > implementation of a Help technology? I'm assuming that this > is referring to the technology itself (i.e., Web Help, HTML > Help, Java Help, AIR Help, etc.), not how an individual > implements their Help system. We're not trying to pass > judgment on individual implementations if they are lacking > certain features, right? > > We're probably saying that Notepad would not be considered an > online Help delivery mechanism (although in some cases, that > actually is the "online Help" provided with a product). > > I think that we should be careful about saying what is an > absolute requirement of "online Help", but guide people more > into a best practice category. > > Cheers, > > ...scott > > > > Bruce Nevin (bnevin) wrote: > > Good point about > > > > * In-topic links, if provided, support navigation to other topics. > > (Like a website.) > > Moving this to the list of "Typical characteristics", > changed as follows: > > * Topics may include links to other topics or to external resources > > (as in a website). > > > > (It's redundant to say that in-topic links support > navigation, kind of > > like saying links link.) And yes, the "typical > characteristics" MUST > > be supported. It doesn't matter that they're optional. The > distinction > > between essential and typical is valid but doesn't let us off the > > hook. > > /B > > > > > -------------------------------------------------------------- > ---------- > > *From:* Goolsby, Chris [mailto:cgoolsby@ptc.com] > > *Sent:* Monday, January 24, 2011 11:11 AM > > *To:* Bruce Nevin (bnevin); > dita-adoption-help@lists.oasis-open.org > > *Subject:* RE: [dita-adoption-help] definition of Help > > > > Ok, I like this a lot better. > > > > One last thing I wonder about is the in-topic links. We say they > > support navigation to other topics. However, links in > some of our > > help topics go to external sources such as referenced web sites. > > So I guess what you're getting across there is that internal > > linking in the help system must be supported, but is > not exclusive? > > > > Chris > > > > *From:* Bruce Nevin (bnevin) [mailto:bnevin@cisco.com] > > *Sent:* Monday, January 24, 2011 10:40 AM > > *To:* dita-adoption-help@lists.oasis-open.org > > *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 is. > Our 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 > > <mailto: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_Technologi > es_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 > <mailto:tself@hyperwrite.com>> > > *Cc:* <dita-adoption-help@lists.oasis-open.org > > <mailto: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 > <mailto: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 > > <mailto:cgoolsby@ptc.com>; > > dita-adoption-help@lists.oasis-open.org > > <mailto: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 > > <mailto:bnevin@cisco.com>> > > *To:* ian balanza-davis <ibalanza_davis@yahoo.co.uk > > <mailto:ibalanza_davis@yahoo.co.uk>>; > cgoolsby@ptc.com > > <mailto:cgoolsby@ptc.com>; > > dita-adoption-help@lists.oasis-open.org > > <mailto: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 > > <mailto:ibalanza_davis@yahoo.co.uk>] > > > Sent: Friday, January 21, 2011 2:58 PM > > > To: Bruce Nevin (bnevin); cgoolsby@ptc.com > > <mailto:cgoolsby@ptc.com>; > > > dita-adoption-help@lists.oasis-open.org > > <mailto: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 > > <mailto:cgoolsby@ptc.com>] > > > > Sent: Friday, January 21, 2011 2:12 PM > > > > To: Bruce Nevin (bnevin); > > > >dita-adoption-help@lists.oasis-open.org > > <mailto: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 > > <mailto:bnevin@cisco.com>] > > > > Sent: Friday, January 21, 2011 12:47 PM > > > > To: dita-adoption-help@lists.oasis-open.org > > <mailto: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 > > <mailto:tself@hyperwrite.com>] > > > > Sent: Thursday, January 20, 2011 8:44 PM > > > > To: Bruce Nevin (bnevin); > > > >dita-adoption-help@lists.oasis-open.org > > <mailto: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 > > <mailto:bnevin@cisco.com>] > > > > Sent: Friday, 21 January 2011 8:43 AM > > > > To: dita-adoption-help@lists.oasis-open.org > > <mailto: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 > > > > --------------------------------------------------------------------- > 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 > >
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]