#119: Contextual help portlet

Contents
  1. Motivation
  2. Proposal
  3. Implementation
  4. Risks
  5. Participants
by David Convent — last modified Jan 21, 2010 07:26 AM

A common problem with users new to Plone after the first install is "what do I do now"? This proposal aims to provide Plone with the capability for contextual help, and to make that help text customizable for a particular deployment if needed.

Proposed by
Alexander Limi
Seconded by
Martin Aspeli
Proposal type
Architecture
State
deferred

Motivation

Currently there is no way to show the user contextual help in Plone. Some examples would be:

  • What can you do from the folder contents screen?
  • How does the state pulldown work?
  • What are content types?

For a customer project, we developed infrastructure for contextually dependent actions, and we would like to reuse this infrastructure to display contextually dependent help in the Plone interface.

This is a critical part of the first impression you get when you have just installed Plone and are wondering what to do next.

Proposal

We would like to have available a Contextual Help portlet in Plone.

It should ideally contain the 3-4 most commonly asked questions or relevant explanations for that particular context.

An example would be the Folder Contents screen:

  • How do I order items?
  • How can I chance the state of multiple items in one operation?

There also needs to be an easy way for Plone and its third party components to load content into the help system. This involves importing text and images from the filesystem.

Implementation

Some of this work has been started, and is owned by David Convent. However, that code is in need of a refresh, and needs to be completed and polished.

Risks

  • Too much Happytalk™, to many help entries in a specific context. The contextual help should be short, succinct and to-the-point.
  • Performance — we have tested it in production, and although it does impact performance, its impact should be small. This should be benchmarked and verified, though.

Participants

David Convent, Jonathan Lewis, Denis Mishunoff, Osman Tartanoglu

Comments (2)

Jonathan Lewis May 12, 2006 04:14 PM
In the future it would be good to be able to use more logic in order to provide more accurate help. For example, the contextual help would know if the login portlet is being displayed or not; if not, it wouldn't tell the user to look for a login portlet. And this might be taken further to assist the user, so that for example the login portlet CSS is changed to a bright red border to show the user where it is. Mac OS help used to do something like that, and I quite liked it. Obviously that's a good way down the road. We would face the usual problems of how far, and how, to separate content and logic. [Jonathan Lewis]
Justin Ryan Mar 20, 2007 06:59 AM
A long time ago I worked on an application where we tried to design a contextual help system which could be aware of issues affecting a specific context, subapplication, etc.. We had nowhere near approaching the infrastructure to do this, but it may be possible to have a problem or issue trackr in a site which is aware of content types, speecific views, etc.. and can display in a portlet a note indicating that a problem has been reported with the tool someone is using, and allowing them to vote to confirm or deny based on their own experience.

The implications of this sort of tool are mind blowing IMO. I talked with David Content about it and he agrees with this approach but hasn't had time of late, so I thought I would record the idea.