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?

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




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





 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.




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]