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:]
Sent: Monday, January 24, 2011 11:11 AM
To: Bruce Nevin
(bnevin);
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:]
Sent: Monday, January 24, 2011
10:40 AM
To:
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:]
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
