My Help Sheet Needs Some Help

The poor help sheet.  It never gets any attention.  Yet, it is an incredibly important piece of your user experience that should not be overlooked.  Many of us have copy/pasted/adjusted derivatives of this:

Now this is a very old example straight from the QlikView Demo site, but I have used something similar to this for too long, choosing to spend my attention on the other aspects of my design.

The old-school help sheet suffers from several issues. 

First, the browser-agnostic environment of today has brought in issues off differing treatment of alignments and kerning.  So, if we use a traditional layering of icon text objects on top of text objects with paragraphs of text, you will get differing results depending on the browser being used.  Here is an example of a sheet I used that was viewed later in Google Chrome:

Secondly, I have found that the copy/paste method is not scalable.  When the product features change, it would be better to manage the help descriptions and icons from a central location that could then be dispersed to all my apps.

Lastly, many environments still use both the AJAX and the IE Plugin client.  This creates yet another issue in that the menu icons look completely different for each client.  It sure would be convenient if we could tell which client is being used and then display the appropriate icon set.

I have handled these issues for my own development, so I thought I would share J

Help Template

You can find the template and the files I am using to populate it here: help_template_repository.zip

The solution consists of first cropping pictures of all the different icons you wish to use in your help sheet.  This was completed with an example document opened first in AJAX and then with the IEPlugin so I could get all the possible icons. 

Then, a spreadsheet was created to house the names of all the pictures, id, client, category and description.  I also created another worksheet to house my larger chunks of text that would be shown in the help sheet.

Store all of this where your QVWs can reference it. 

Then I had to handle the loading of this.  I chose to create a txt file that I could manage outside of QlikView that could be referenced with an include statement:

$(Include=c:\qlikview documents\qv production documents\qlikview communal\include\help\help_bundle_load.txt);

Within the txt script, we first have to set variables with the paths of the icon repository and the spreadsheet.  I used the full UNC paths since QVWs using it might be scattered about the server.

SET vHelpDataPath = 'C:\QlikView Documents\QV Production Documents\QlikView Communal\Data\Help\Help_Text_Standard.xlsx';
SET vHelpIconPath = 'C:\QlikView Documents\QV Production Documents\QlikView Communal\Graphic\Help\';

Then we load the xls worksheets.  To get the actual pictures loaded into the QVW we use the BUNDLE LOAD.  This actually embeds the pictures into our documents.  Care should be taken with this function to ensure you are not loading a large number or large sized pictures as this would hinder performance.

BUNDLE INFO LOAD Picture_ID, '$(vHelpIconPath)' & [Picture_Name]
RESIDENT Help_Icons;

Lastly, we need to reference all of this data in our help sheet.  To load blocks of text, I created text objects with expressions like this:

=Minstring({<Help_ID = {2}>}Help_Text)

For the icons, I chose to create charts to display them, rather than trying to layer each one in between pieces of text.  You can create a chart with Picture_ID as the dimension, then Hide that column.  I then used two expressions, one to show the icon picture and one for the text descriptor. 

Notice the use of ClientPlatform().  This function will return nothing if the user is on the IEPlugin.  It will return the name of the browser if the user is on the AJAX client.  With this function, we can display only the appropriate set of icons to each user. 

The INFO function tells QlikView to display the embedded file associated with the field, rather than displaying the text.

Picture:

=IF(LEN(ClientPlatform())>0,
                MINSTRING({<Picture_Category={'Selection'},Client_Type={'AJAX'}>}INFO(Picture_ID)),
                MINSTRING({<Picture_Category={'Selection'},Client_Type={'IE'}>}INFO(Picture_ID)))

Text:

=IF(LEN(ClientPlatform())>0,
                MINSTRING({<Picture_Category={'Selection'},Client_Type={'AJAX'}>}Picture_Text),
                MINSTRING({<Picture_Category={'Selection'},Client_Type={'IE'}>}Picture_Text))

You will have to set the picture expression to Representation: Image and select “Keep Aspect” from the Image Formatting dropdown.

Final Result

I still manually create example charts and controls representative of my data to fill out the rest of the help sheet, but at least the main portions of my help sheet can be easily created and centrally managed. 

After adding the rest of my data model and the supporting charts, here is my finished product opened in AJAX and then with the IEPlugin:

I always welcome your comments and suggestions.