Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [platform-help-dev] Re: [platform-doc-dev] new help system proposal

platform-help-dev-admin@xxxxxxxxxxx wrote on 11/22/2004 05:50:48 PM:

> Gary wrote:
> 
> Disclaimer: I'm a help author, not an engineer, and am probably 
> missing something when trying to understand the need and 
> implementation of this proposed help feature for OS-specific 
information.
> 
> Following along with the discussion, it seems that someone has a 
> desire to package platform-specific help graphics separately, 
> perhaps to reduce the install image size for each platform. It 
> sounds like a neat idea and there are possibly other benefits, too, 
> I'm not sure.
> 
> But when looking at the agreed upon implementation, with its 
> similarity to the NL way of organizing things, it raised a question 
> in my mind.
> 
> konradk@xxxxxxxxxx wrote:
> > Enhancing help system to search paths under os specific locations 
like: 
> > os/linux/x86/doc.zip!file, 
> > os/linux/doc.zip!file, 
> > nl/zh/CN/doc.zip!file, 
> > nl/zh/doc.zip!file, 
> > doc.zip!file, 
> > os/linux/x86/file, 
> > os/linux/file, 
> > nls/zh/CN/file, 
> > nl/zh/file, 
> > file solves the problem. Windows screen capture can be packaged in
> doc.zip of a
> > plug-in as done today, and Linux fragment can be later added with 
> os/linux/doc.zip
> > containing a Linux equivalent image. 
> 
> So, if I understand it correctly, if the help system wants an OS-
> specific graphic, it goes to a an OS-specific directory to get it, 
> and if it doesn't find it, goes to the NL directory, then to the 
> default doc directory.
> 
> But, what if the help system needs a graphic that is _both_ OS and 
> NL specific? For example, what if a user has a need to see a screen 
> capture of an AIX system with Chinese text? In which doc.zip would 
> the help author put such a file? If I put it in the os/aix/doc.zip, 
> then how do I differentiate the language? And if I put it in 
> nl/zh/CN/doc.zip, then how is the OS differentiated?
> 
> ----
> I'm assuming the proposed new feature is suggesting separate 
> folders. That is, either:
> 
> com.mycompany.doc.nl1
> com.mycompany.doc.os1
> 
> or...
> 
> com.mycompany.doc/nl/cn/zh
> com.mycompany.doc/os/aix
> 
> It seems that in order to handle the case that I brought up, some 
> multiplicative or inclusive tree structure is needed. For example,
> 
> com.mycompany.doc/nl/zh/CN/os/aix
> com.mycompany.doc/os/aix/nl/zh/CN
> 
> or
> 
> com.mycompany.doc.nl1/zh/CN/os/aix
> com.mycompany.doc.os1/aix/zh/CN
> 
> But, if this is true, then where do you stop? The plugin directory 
> structure could expand to umpteen factors if it's decided that 
> things need to be divided even further, such as by UI or Windowing 
> system (KDE, Gnome, Motif, ...) or user experience (expert/novice).
> 
> In such a scenario where there are many factors, Eclipse would have 
> to include a Cloudscape or MySQL plugin just to manage the 
> attributes and decide which help topics to present. ;-) The CSS idea
> could work (or even an XSLT-dynamically transformed XML topics, if 
> it were possible). Although you wouldn't get the nice cascading 
> default that Konrad suggests.
> 
> -g-

Hi Gary:

If I understand the conversation that occurred in this thread prior to
your post, I think the consensus is that the CSS approach by UI framework
is the only reasonable approach to follow at the moment.

Using the CSS approach, the plug-in structure for a component that 
provides
gtk and mswin screenshots would look something like:

- com.name.component
- com.name.component.nl
- com.name.component.gtk
- com.name.component.gtk.nl
- com.name.component.mswin
- com.name.component.mswin.nl

And the content of a help topic in com.name.component that provided
framework-specific content would look something like:

<p class="gtk">To open the component window, press the F1 key.</p>
<p class="mswin">To open the component window, press the CTRL+F1 key.</p>
<p>The component window opens to the "New Component" wizard:
<img class="gtk" src="../com.name.component.gtk/component.png">
<img class="mswin" src="../com.name.component.mswin/component.png">
</p>

The localization of the text and screenshots would be handled by
the current existing NL fragment support in Eclipse. And the CSS setting
themselves (turning on one UI framework, and turning off the other UI
frameworks) would presumably be placed either in the primary feature
or set dynamically and inserted into the head of each page -- I seem
to recall that that capability had been added to Eclipse 3.0.

Ben, Konrad -- can you confirm that I'm on the right path here?

After discussing the proposal with my colleague (Jamie Roberts), the
only concerns we have with the proposal are the following:

* Accessibility: we want to ensure that the resulting help system is
still accessible through a screen reader, i.e. that a screen reader
wouldn't simply ignore the { display: hidden } CSS setting and read out
all of the displayed and hidden text. My experience with JAWS and IBM
Homepage Reader is that they read exactly what Internet Explorer displays
(to the point of ignoring CSS directed at screen readers), but it would
be worthwhile confirming that this is still the case.

* Search results: Because Eclipse search does not care or understand
CSS, it will return search hits for all text that is hidden by CSS.
There will need to be strong guidelines for writing UI framework-specific
content -- for example, rather than having a single HTML page that 
documents
the key bindings for every UI framework in several different tables, with
only a single table displayed through CSS settings, there should be 
separate
HTML pages for each UI framework. Using CSS to substitute text at the 
individual
sentence level for key-binding phrases, on the other hand, is probably 
fine
(although it will subtly affect search rankings). This concern can be
addressed with solid guidelines.

* Information center use case: This seems to be assuming the use case of
the help system integrated with Eclipse tooling -- but what happens in the
case of a Linux client connecting to an information center hosted on 
Windows?
For the base documentation plug-ins we're discussing, this probably isn't
a major issue, but if the approach is extrapolated beyond base plug-ins
into a common practice we have to keep the user context in mind. It would
be awfully frustrating to search for help on performing some task in 
Linux,
get a search result (based on the CSS-classed text), only to find that the
text is hidden because the information center is running on the wrong
platform. I suppose this is where the client-detection algorithm would
come in handy.

Assuming these concerns are addressed, we think that the proposal is
an excellent step forward to enabling a better user assistance experience
for users of heterogenous operating systems.

Dan


Back to the top