Hi
Bruce.
I’ve
added a couple of comments to yours below in
italic.
From: Bruce Nevin
(bnevin) [mailto:bnevin@cisco.com]
Sent: Tuesday, April 27, 2010
2:58 PM
To: dita-help@lists.oasis-open.org
Subject: RE:
[dita-help] topic (as requested): what's different about
OLH?
An
AI for me in the minutes received before our last meeting brings this back up
to the top of the stack.
5. General discussion: What's unique to DITA online help?
(The question was actually what's unique about OLH wrt other forms of information delivery. And indeed the diffrentiators listed below are not specific to DITA.)
- Bruce asked the DHSC what it perceived to be unique about
OLH implementations of DITA?
- Tony summarized that the following are common
differentiators.:
> tripane presentation
> context-sensitive hooks to product UI
> window definitions and behaviors
> Non-linear access to or use of the information
- DHSC members also recognized that other controls and features
often associated with OLH such as expandable sections,
hover help, and popups are as common in web design and
programming as in OLH. Members perceived lots of crossover
with the DITA for the Web SC.
- AI/Bruce: Offered to send an email to the group to get more of
this discussion cooking via email.
No
further discussion has been 'cooking' since Tony took this up a couple of
weeks ago.
Here
are a few further responses embedded in context within Tony's reply
below.
From: Tony Self
[mailto:tself@hyperwrite.com]
Sent: Saturday, April 10, 2010 8:59
AM
To: dita-help@lists.oasis-open.org
Cc: Bruce Nevin
(bnevin)
Subject: RE: [dita-help] topic (as requested): what's
different about OLH?
Dear
Bruce
Sorry
it’s taken me a while to respond.
I
think an issue identified by an SC of the DITA TC, it is likely that the
recommendation addresses some shortcoming of the specification. I think It
is less likely that the SC of the DITA TC will identify a problem that needs
resolving by tool vendors. That’s more likely to be the role of an Adoption
TC subcommittee, as the Adoption TC is responsible for removing such
impediments to adoption.
This
is an interesting take on the relative responsibilities of the TC and the AC.
You're speaking here for the SC of the TC. What's the status of the SC of the
AC?
Regarding
the proposed DITA Help SC for the Adoption TC, I’ve taken on the task to put
together a draft charter for review by this team and then proposing the new SC
to the AC. I expect to that at the next meeting once the AC is past the
current review of the latest DITA spec.
The
TC'sEnterprise Business Documents SC (BusDocs) has some analogous questions to
work on.
My
question, however, was about the relation of a SC to its parent Committee. The
SC's deliverables do not go to the public, they go to the parent TC.
In
the case of the DHSC, we have a draft recommendation for DITA 1.3 to add
some new elements to store context hooks and window descriptions. That’s
clearly a spec issue.
This
goes to the DITA Technical Committee (TC).
Yep.
However,
we have also produced a guide to creating Help systems from DITA source, and
that provides things such as suggestions for customising part of the OT,
details of OT plug-ins that are available, instructions for using some
commercial tools to process DITA where it is otherwise unclear,
etc.
This
goes to the DITA Adoption Committee (AC).
Yep.
Tool
vendors may indeed use that guide in their internal product development
discussions, but that’s none of our concern.
I'm
proposing that there are aspects of OLH development that require better vendor
support -- to conceptualize, think of the delta between a HAT and a desktop
publishing system like Word or FrameMaker. Are there XML/DITA editors that
function as a help authoring tool like RoboHELP? It seems to me that this is a
case of oversight and neglect by vendors rather than primarily an impediment
to adoption, and my suggestion is that we might do well to
bring that delta to the fore so that vendors are aware of it. Their
decisions will probably be based on their perception of the size of the
market for HAT functions more than on the technical issues.
Actually,
PTC does have a product that enables you to use a specialized DMP map to
develop an online Help System. It’s covered in the guide Tony mentions above,
and I demoed it to this SC a long time ago. I can provide more details if you
are interested.
The
answer to your specific question about “how do we create... the OLH” is to
use the DITA Help Technologies Guide for guidance. If we go deeper than
that, and refine the question to “how do we make sure people create
minimalist, well-organised, and effective Help systems using DITA”, then I
think that’s outside the ambit of OASIS. A parallel might be the W3C trying
to take responsibility for the quality of information in HTML pages.
Right
you are, that aspect is subordinate context of what we're addressing
here. It crept in through the quoted text from a broader conversation
elsewhere. That conversation was with a colleague who has carved a niche for
himself supporting a system for 'single sourcing' online help from Framemaker
book files. A few bits might be filtered as conditional text by some authors,
but by and large the TOC for the book is the nav for the OLH, and other links
are whatever made sense for the book author. A twofer is very appealing from a
management point of view, but 'single sourcing' is a much richer concept in
the DITA world. And is this type of OLH the best service to the user?Those
who feel that no more is needed will have little or no interest in HAT
functions in authoring tools. So my advocacy of them is predicated on the
belief that there is a role for the Help developer and that OLH can and should
be more than a different rendition of the same source content that is used for
a book. Interest in discussing it here further stands or falls on the same
basis.
I
think the responsibility for creating good quality DITA-based Help and
documentation generally belongs with the community of technical
communicators... through their professional societies, their training
providers, and their educational institutions. It might be different in
other countries, but even if the community raised the quality of
documentation produced by its members, many technical documents are produced
by “non technical writers”... people from outside the community. In many
cases, unqualified, poorly skilled people.
Anyway,
that’s my tuppence worth.
Tony
From: Bruce Nevin
(bnevin) [mailto:bnevin@cisco.com]
Sent: Tuesday, 30 March 2010
9:28 AM
To: dita-help@lists.oasis-open.org
Subject:
[dita-help] topic (as requested): what's different about
OLH?
First,
a question about SC process. Any issue identified by a SC goes to the TC,
and its resolution is by one or more of
- DITA 1.3
- OTK
- Tools
vendors
So
it seems to me the SC focus is on problem definition, with some
recommendations how it might be resolved, but without implementation detail.
Is that the consensus about process?
I
raised the question "What's different about OLH?" This has two aspects,
input and output so to speak:
- Presentation and manipulation in the
authoring environment.
- Rendering of DITA topics as OLH (OT & other
XSL/FO).
In
both cases, how do we create the nonlinear or multilinear organization of
topics in OLH (and in Web content)? That's the more specific question that I
raised.
______________________________________
The
following may be more discursive than you want. Just stick with the above if
that's appropriate.
The
discussion that I mentioned was with a colleague who champions a system for
single sourcing OLH from FrameMaker book files. It turned out that
his preference is to RTFM and learn the product, after which he says a
Help system has nothing useful to say to him. (He complained that the OLH
focused on doing small modular tasks and assumed he knew what the
application was for. Apparently he never found the overview topic. Or maybe
there wasn't one.) Give those users a PDF book, I say.
But
teaching is only one function of documentation. Other users want just the
bit of information they need, and then they want you to get out of their
face so they can get on with it. Think of a user with some knowledge and
skill doing something unfamiliar, or needing to refresh memory about
something seldom done. And even with instruction, there are different
cognitive styles and different learning styles. One metaphor that has been
used is of search parties, one combing the woods with a long line
systematically beating the brush, the other in helicopters, scanning for
likely places then zooming in to look close up. I don't have the same
learning style as my friend studying the manual so that a new tool can't
surprise him.
Much
is made of minimalism. But terse is better until and unless more is better.
Progressive disclosure accommodates different levels of knowledge, skill,
and (let's be frank) intelligence. The converse is also true. More is
better unless and until less is better, or terse is better. As with
instruction and learning, one size definitely does not fit
all. Writers have to put themselves in the readers'
shoes--all of those several rather different pairs of shoes. Progressive
disclosure is easier on line, where the information can expand to a virtual
100 pages if that user needs that much on that occasion, but other users
don't have to wade through 100 pages to find just the bit that is needed.
And progressive disclosure is only part of the solution, because the problem
is not just start terse and add more if they ask for it, it's a problem of
showing only what's relevant at that point. That's where embedded help tries
to go.
Another
valid criterion for good OLH is to maintain the reader's context. Rollover,
expanding text, secondary windows (if necessary), and other methods keep the
reader rooted to their starting point if they start drilling down through
links. That said, users generally have developed relevant skills in
navigating the web, so they're less likely to get confused and lost in
link-land these days.
UI
design works hard to be 'intuitive' and make documentation unnecessary. The
failure points of this effort are somewhat unpredictable by user and by
occasion. It's at those points that quick access to relevant information is
needed--for those users for whom the UI fails to make it obvious what to do.
I
don't know if it's cognitive style, or bad prior experiences, or what, maybe
a self-image thing about 'admitting' that you need help. Or like my
colleague who I described at the outset, the guy who studies the manual to
master the product first and says that Help has nothing useful to tell him.
Fred, the engineer I worked with on a network management product, was at a
customer site. The user was stuck. Fred suggested he try the Help. Bang,
there was a short topic with the answer to his question, right in front of
him. "Ah, I can never find what I want in these things!" said he, and closed
the window. If users don't click the Help link or the F1 key, the
information stays in the Help ghetto. Hence, the need to distribute the
information throughout the UI so that it's just part of how the UI works,
rather than separate 'documentation'.
Quick
access to relevant information is the grail. So criteria for OLH might
include:
- Rapid
access (t < 30s)
- to
'relevant' content, where `relevant' means
- My
questions are answered.
- I
better understand how to use the product.
- with
the proviso that if my question is based on misconceptions, the content
responding to them should lead me to reframe the question in a more
appropriate way and look again.
How
can the TC, the OT, and tools vendors collaborate to get all that from
DITA?
/Bruce