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:]
Sent: Monday, January 24, 2011 8:56 AM
To: Scott
Prentice;
Cc:
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:]
Sent: Monday, January 24, 2011 1:30
AM
To: <>
Cc:
<>
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" <>
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:]
Sent: Monday, 24 January 2011 11:10
AM
To: <>
Cc:
<>
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" <>
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:]
Sent:
Saturday, 22 January 2011 8:16 AM
To: Bruce Nevin (bnevin); ;
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) <>
To: ian
balanza-davis <>;
;
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:]
> Sent: Friday, January 21, 2011 2:58 PM
> To: Bruce Nevin
(bnevin); ;
>
>
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:]
>
> Sent: Friday, January 21, 2011 2:12 PM
>
> To: Bruce Nevin (bnevin);
> >
>
> 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:]
>
> Sent: Friday, January 21, 2011 12:47 PM
>
> To:
>
> 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:]
>
> Sent: Thursday, January 20, 2011
8:44 PM
> > To: Bruce Nevin
(bnevin);
> >
>
> 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:]
>
> Sent: Friday, 21 January 2011
8:43 AM
> > To:
>
> 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
