OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

dita-help message

[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.




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
- 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:

  1. Rapid access (t < 30s)
  2. to 'relevant' content, where `relevant' means
    • My questions are answered.
    • I better understand how to use the product.
  1. 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?



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]