[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
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. 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. 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.
Tool vendors may indeed use that guide in their internal product development discussions,
but that’s none of our concern. 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. 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] 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 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: 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:
How can the TC, the OT, and tools vendors collaborate to get all
that from DITA? /Bruce |
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]