# UI of Gestures Collector

Version:
  $Date$
Author:
  Jaroslav Tulach
Abstract:

  Proposal of scenarios and UI to satisfy usecases for UI Gestures Collector.

# Scenarios

### Scenario: We need returning users

Important user actions are recorded and remember in the system when the UI Gestures Collector is installed. In order for the gesture collector to be useful, it is necessary to convince the user to upload these information to our collecting server for processing. As we need a wide range of submittions, it is important that the same user continous to submit these logs repeatedly.

It is important to find the right moment for offering the user to do the upload. Current proposal counts with two options - when an exception occurs, the user is offered to send feedback to the server, also there is a UI button in the status bar that shall visually attract user attention and encourage him to submit the data.

The range of "useful information" is wide and can be improved in future, however for purposes of this document it is enough to think about it just as an inteligent "Tip of the Day". Based on the submitted data and possibly the previous UI logs already submitted to the server, it is possible to select more appropriate "tip of the Day". In the simplest scenario it is definitely possible to find out what project types the user is using and not show tips about web projects, if it is writing just plain Java applications.

By trading a useful information back for the user's submission of the UI Gestures data, we establish an equal and benefitial relationship with them and encourage them to submit the data in future as well. It is believed that mutually benefitial approach supports returning customers.

### Scenario: We need confident users

Not all people like to sign bianco checks. Many of them do not like to send information about themselves to someone else. We need to gain a certain amount of trust and convince them that sending data gathered by UI Gestures Collector is safe. Indeed one way to built the trust up is the trading of useful information back as described in previous chapter, however this starts to work only for subsequent submission, still we need to convince the user that first submission is safe.

To do that the user will be given a chance to view and examine the content of the data to be submitted. The main submit screen will have a button to open a view of the logged data, the user will be able to browse thru them and then submit or cancel the transfer. There will be two views - one human friendly - a list with records, icons, descriptions, etc. Second raw data - some kind of not very human readable XML in a text editor that represents the actual data to be sent to the logging server.

### Scenario: We need to not scare newcommers

The submission dialog shall not open too "early". Instead it shall wait for some time, to let the user try and see that the NetBeans based product is worth to use and it is worth to contribute to the project efforts.

That is why there should be a limit of actions that the user has to perform before its attention is drawn to the process of submission. That is why there will be a toolbar button counting the actually performed user actions and if there will be more than 500 of actions the button will start to visually indicate that it should be pressed. If done, then the UI Gestures Collector dialog for submissions will open.

### Scenario: We need reliable submissions

We are not interested in logs from people who just play with the system (especially testers). We need real data and we need the data to be of the same quality - e.g. contain similar amount of information.

This should be achieved the "action limit" of 500 described in previous section. If the user is encouraged to submit the logs after 500 actions, then most of the logs will contain data of the same size and as such they will be of similar level of value for analysis.

### Scenario: Easy bug reports

Easy bug reporting is critical to improving quality of any product. Many products include some "Dr." functionality that allows easy bug submission in case of failure. That is why it is expected that many users are going to see a failure as a natural moment for submitting a feedback to netbeans.org project.

The exception dialog will be enhanced to contain a submit button and open the UI Gestures Collector dialog.

# Ascii Art

### Submittion Button

This button shall be placed in a status bar and shall encourage user to click on it and upload data to the server:

    /---\
    |   |
    \---/

The button visually indicates the growing number of so far recorded events by being a "circle" with an "arc" of already recorded actions from the expected maximum (currently 1000).

### Submittion Dialog

This dialog appears when the user presses the button in status bar:

    +-------------------------------------------------------------------------------+
    | UI Gestures Collector                                                       X |
    +-------------------------------------------------------------------------------+
    |                                                                               |
    |                                                                               |
    |                                                                               |
    |                                                                               |
    |                                                                               |
    |                                                                               |
    |                                                                               |
    |         An HTML page describing the purpose of UI Gestures Collector          |
    |      encourages to send the data, for the trade of nice statistics            |
    |                                                                               |
    |                                                                               |
    |                                                                               |
    |                                                                               |
    |                                                                               |
    |                                                                               |
    |                                                                               |
    |                                                                               |
    |                                                                               |
    |  [[_V_iew Data]]                             [[_S_ubmit Data]]   [[_C_ancel]] |
    +-------------------------------------------------------------------------------+

### Examination Dialog

When the user chooses to see the data about the be transfered to the server, then he will get following dialog. They are available in two forms, the raw one is just one huge XML document which precisely describes the bits to be sent to the server. The Structured view splits the document to individual records:

    +-------------------------------------------------------------------------------+
    | UI Gestures Collector                                                       X |
    +-------------------------------------------------------------------------------+
    | Structured | Raw |                                                            |
    |-------------------------------------------------------------------------------|
    | list with records, first is the newest one                                    |
    | second is the second newest one                                               |
    | 3rd                                                                           |
    | 4th                                                                           |
    | 5th                                                                           |
    | 6th                                                                           |
    |-------------------------------------------------------------------------------|
    | The exact text of the select record to be sent to server. XML format.         |
    | <record>                                                                      |
    | <message>Invoking Build </message>                                            |
    | </record>                                                                     |
    |                                                                               |
    |                                                                               |
    |                                                                               |
    |                                                                               |
    |                                                                               |
    |                                                                               |
    |-------------------------------------------------------------------------------|
    |  [[_H_ide Data]]                              [[_S_ubmit Data]] [[_C_ancel]]  |
    +-------------------------------------------------------------------------------+

### Error Dialog

When an exception is rised, its behaviour remains the same as is usual - e.g. in develpment builds to common "Unexpected Exception Dialog" is shown, in releases a blinking icon at the lower right corner starts to blink and when clicked the dialog is shown. However in contrast to previous versions, there is a new button _R_eview and Report Problem in the dialog. When clicked it opens following dialog:

    +-------------------------------------------------------------------------------+
    | Report Problem                                                              X |
    +-------------------------------------------------------------------------------+
    |  If you want to get informed about the state of this problem,                 |
    |  you need to be a registered user. If you're not registered,                  |
    |  you can register here,                                                       |
    |  or you can send a report as a guest.                                         |
    |  Summary:  |_______________________________________________________________|  |
    |  Describe what you were doing when the exception occured:                     |
    |   _________________________________________________________________________   |
    |  |                                                                         |  |
    |  |                                                                         |  |
    |  |                                                                         |  |
    |  |                                                                         |  |
    |  |                                                                         |  |
    |  |                                                                         |  |
    |  |                                                                         |  |
    |  |                                                                         |  |
    |  |_________________________________________________________________________|  |
    |  ---------------------------------------------------------------------------  |
    |  Username: |____________________| (Your NetBeans.org username)                |
    |  Password: |____________________| Username or password is wrong               |
    |            [x]Send report as a guest                                          |
    |  The report contains UI gesture data collected prior to the exception.        |
    |  [[_V_iew Data]]                                    [[_S_end]]   [[_C_ancel]] |
    +-------------------------------------------------------------------------------+

User can fill his user name. After that we could contact him for more information, but this item is not needed, so he can check send report as a guest button. Issues from not registered users won't be so usefull, but better then nothing. Summary is going to be initially set to exception class and exception message, if there is some, but we are giving user a possibility to change this item. User can fill short description what has happen to him. After pressing Next button password is checked and report is send directly for corect password. For wrong password "Username or password is wrong" message is shown and dialog stays enabled.

After pressing View Data Examination Dialog appears, and Hide data button is added.

    +-------------------------------------------------------------------------------+
    | Report Problem                                                              X |
    +-------------------------------------------------------------------------------+
    | Structured | Raw |                                                            |
    |-------------------------------------------------------------------------------|
    | list with records, first is the newest one                                    |
    | second is the second newest one                                               |
    | 3rd                                                                           |
    | 4th                                                                           |
    | 5th                                                                           |
    | 6th                                                                           |
    |-------------------------------------------------------------------------------|
    | The exact text of the select record to be sent to server. XML format.         |
    | <record>                                                                      |
    | <message>Invoking Build </message>                                            |
    | </record>                                                                     |
    |                                                                               |
    |                                                                               |
    |                                                                               |
    |                                                                               |
    |                                                                               |
    |                                                                               |
    |-------------------------------------------------------------------------------|
    |  [[_H_ide Data]]                              [[_S_ubmit Data]] [[_C_ancel]]  |
    +-------------------------------------------------------------------------------+

Hide data button moves the user back to Error dialog. He can fill description and submit data there.