Context-Sensitive Help
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://
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-
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/
[
{
},
"project/
[
{
},
{
}
{
},
]
}
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://
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
- Started by
- Completed by
- Cindy Lu
Related branches
Related bugs
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.