Context-Sensitive Help

Registered by Don Domingo on 2015-05-29

Context-sensitive Help allows the dashboard to dynamically provide users with links to relevant content, depending on the user's location in the dashboard (ie. their 'user context). This implementation should also allow developers to easily define links to serve for each specific context, and also for each vendor to seamlessly customize those links for their respective distributions.

Motivation:

Currently, the current dashboard implementation only allows deployers to one link for the header's 'HELP' button. We can improve the user experience siginificantly by making this button context-sensitive. Aside from making it easier for users to find information relevant to their context, this also gives developers the opportunity to put the most helpful information for a feature or functionality right in front of the user, and at the exact moment the user needs it the most.

Description:

At present, if a value is assigned to 'help_url' in 'settings.py', then a HELP button will appear in the header of the OpenStack dashboard. The HELP button points to the 'help_url' value.

The easiest implementation of context-sensitive help would involve the following components:

    Context Parser
        This will help identify the current context of a user. The quickest
        method for doing so would be through the current URL that the user
        is on.

    HELPLINKS.json
        This is a configuration file that defines user contexts and appropriate
        entries for each context. Each entry should point to relevant content
        for the context, and should contain a URL, title, and description of
        the content. Presumably, each unit of content here would be an existing
        web page that the user should have access to (eg. content from
        http://docs.openstack.org)

    Help Pop-Up
        An application that procedurally generates a pop-up page containing the
        links specific to a user's current context, as defined in HELPLINKS.json.

If a defined context has only one link, then the Help Pop-Up will automatically open a pop-up directly to that link, similar to how the HELP button opens a new tab to the defined 'help_url' right now.

If a user's context is not defined is HELPLINKS.json, then the Help Pop-Up will simply fall back to opening a new tab to the current 'help_url'.

Within this framework, OpenStack vendors can customise the context-sensitive help of their distribution by simply replacing the HELPLINKS.json. This allows a vendor to tailor its customer base's user experience with distribution-specific content. This is particularly helpful for providing content that customers would normally be able to access through a paid subscription; presumably, such links would not be permitted upstream, and therefore would only be implemented at a distribution level.

UX:

There are no further UX implications of this change, other than the pop-up page generated by the Help Pop-Up app.

Testing:

The following snippet contains two sample HELPLINKS.json entries, which correspond to context definitions for 'Volumes' and 'Instances' pages in the dashboard. The 'Volumes' context only has one entry, and therefore clicking 'HELP' should automatically open to that page; the 'Instances' context has three entries, and should therefore pop-up a display containing the defined links.

{

    "project/volumes/":
        [
            {
                "linkurl":"http://docs.openstack.org/user-guide/dashboard_manage_volumes.html",
                "linktitle":"Basic volume usage and configuration",
                "description":"Information on how to perform basic volume management operations (for example, creating, deleting, and attaching a volume)"
            },
    "project/instances/":
        [
            {
                "linkurl":"http://docs.openstack.org/user-guide/dashboard_launch_instances.html",
                "linktitle":"Basic instance creation and management",
                "description":"Information on launching, managing, and tracking instances"
            },
            {
                "linkurl":"http://docs.openstack.org/admin-guide-cloud/content/section_compute-instance-building-blocks.html",
                "linktitle":"Instance building blocks",
                "description":"Provides a high-level description of instances in OpenStack"
            }
            {
                "linkurl":"http://docs.openstack.org/user-guide-admin/dashboard_manage_instances.html",
                "linktitle":"Connect to instances through SSH",
                "description":"Instructions on how to connect to an instance securely through SSH"
            },
        ]

}

Doc Impact:

There should be no additional doc impact for this feature. However, this should not preclude writers or developers from editing the HELPLINKS.json file whenever context-relevant content is added to the upstream documentation suite (http://docs.openstack.org/).

Outside Dependencies:

N/A

Requirements Update Required:

N/A

Blueprint information

Status:
Complete
Approver:
None
Priority:
Undefined
Drafter:
Don Domingo
Direction:
Needs approval
Assignee:
None
Definition:
Obsolete
Series goal:
None
Implementation:
Not started
Milestone target:
None
Completed by
Cindy Lu on 2016-10-28

Related branches

Sprints

Whiteboard

***** 10/28/2016 [clu_] Neat concept, but no work done it. Closing out. If there is work, can reopen.

HELPLINKS.json probably shouldn't be a single file - we need plugins to Horizon to be able to provide context senstive help as well -- maybe this should be a parameter in the relevant panel.py file

Should make sure there is a mechanism to translate link titles + descriptions

ddomingo: ^^ would this mean that defining help content for each help would be decentralized? For example, would the defined help for the volumes and instance management pages be in different files?

doug-fish: ^^yes, that's what I was thinking/assuming. The help content needs to be as decentralized as the code. I'm thinking mostly of the context->help content link with that statement. Maybe it's actually true for the content as well.

(?)

Work Items

This blueprint contains Public information 
Everyone can see this information.

Subscribers

No subscribers.