BluePrint: Inline Help

Introduction

This will use a variety of formats to provide help to the user of the system. This includes tooltips that are linked with the fields in a form and guided tours which can be used to step a user through a particular process.

Documentation using a variety of published media such as video, screenshots and text are difficult to maintain and with a system such as Sahana Eden which rapidly evolves these artifacts are soon out of date. Additionally, much of this material is tied to a template and as the different templates expand to meet user needs capturing the same screenshot for a new template become a chore.

Inline help is independent of templates and will continue to work as the system evolves. Tours can be used to highlighted new material and help new users understand existing processes.

The system currently has tooltips which are tied to the form, but these can't be used to describe how the fields come together to manage a particular workflow.

Stakeholders

This will be used by new users and made available to seasoned users who are trying a new workflow or have forgotten how to perform particular workflow. This will create more text to be managed by the system and so it will add an extra burden on the translators. This can be used to support remote training sessions. Developers can use this system to showcase a new feature. System documentors will have another system to maintain (although the maintenance cost of this will be lower than published material)

User Stories

A new user wants to know what they can use Sahana Eden for. A new user wants to know how to access and use a particular workflow. A seasoned user doesn't want to be hindered by paper clips attached to the system. A manager doesn't want to have to train every volunteer on how to use the system. A user want the inline help to be available in their mother tongue.

Requirements

Requirements for a guided tour

Functional

1. Template functionality
   1. When templates share the same functional interface then they should be able to share the same tour
   2. When templates differ in functionality they should be able to modify an existing tour to reflect the different functionality
2. The template design
   1. Tours should reflect the look and feel of the template
3. The text displayed in the tour
   1. Should be integrated with the translation system
   2. Should be decoupled from the code
4. A user who is not logged in
   1. Should be able to start a tour to get some basic information about the instance
   2. Should not be distracted by a tour if they are trying to log in
5. A user who is logged in
   1. Should be able to start a tour where they left off
   2. Should be able to see what tours are available
   3. Should be able to see what tours they have completed
   4. Should control the speed of the tour (active participation rather than passive observer)
6. An administrator of the system
   1. Should be able to collect anonymized usage data of the tours.
   2. Should be able to make a tour available
   3. Should be able to block access to a tour
7. Designer of a tour
   1. Should be able to create text for a tour and link them to parts of the workflow
   2. Should not need to know any code
   3. Should be able to use database values in their text without having to perform SQL queries (that is the platform does it for them)

Non-functional

1. When not running
   1. they should not have any noticeable impact on the performance of the system.
2. When running
   1. They should never expose information that the user would not normally have the permissions to see.
   2. They should not prevent a user from aborting the tour and any point to perform their expected duties.

Interoperability

Standards

System Constraints

Design

Data Model

Configuration Settings

settings.base.joyride

The name of the template specific tours.

Database Table

pr_person_tour	A new table that will hold information about each tour the person has taken
	person_id obtained from s3_logged_in_person()
	name string
	completed boolean
	place integer the place to resume within the tour, if not completed

Workflows

<Diagrams or Pseudocode>

Site Map

<for User Interface solutions>

Wireframes

<for User Interface solutions>

Technologies

Current Implementation

<Leave open for a list of existing implementation of this solution in Sahana Eden:> <*a brief description of the implementation (date/time, name, design options chosen)> <*a link to the code> <*list of deployments of the implementation> <*links to case studies> <*short analysis of achievements/problems>

Planned Implementation

<List of goals for your implementations which you (include your name/github repo/IRC handle) are currently working on>

Future Extensions

<List of features which could be included, but are outside of the scope of this extension>

Outstanding Questions

<Questions about the features or design that haven't been (and need to be) answered>

References

<Links to external resources>

---

BluePrint