Aktions' Requirements Document



Introduction

Abstract

Computers have become a major aspect of everyday life, creating a need for improved usage statistics. Aktions is a software development kit designed to gather this information. The software helps developers understand how well their software meets user demand through an action-oriented perspective.

This document describes the requirements for the second iteration of Aktions. It contains a general description of the system at large, the functional requirements we expect, non-functional restraints on the project, and possible features for future releases.

Purpose of this document

The purpose of this document is to outline and explain the specific requirements for the second iteration of Aktions. It enumerates the constraints under which the software is developed. Readers of this document should have read our previous requirements document. Readers of this document should have a general knowledge of computers, the Qt libraries, and the KDE Libraries.

Goals

Our primary goal is the creation of 3 components are combined to provide the functionality outlined in the abstract. Those components are as follows:

The goals of this iteration are

Overview of the rest of the document

The rest of this document reflects the requirements necessary to accomplish the goals for this iteration. It contains a general description of Aktions, its main components, and the interactions between them. It enumerates

  1. The functional and non-functional requirements for our first release,
  2. Potential functionality for future releases, and
  3. The projected evolution of the system.

General Description

Clients send data to Aktions through an API. This data is then stored in an information repository. Programs may query the repository for data. The second iteration of Aktions development includes an API and administrative console.

Application Programming Interface (API)

The API provides a unified mechanism to store and retrieve usability information. It encapsulates data gathering, filtering, and retrieval. It exports admnistrative capabilities that group data into studies and tasks, as well as annotate studies and tasks with comments. It also configures Aktions.

Administrative Console

This program creates, administers, and analyzes usability tests. It features a plug-in system that allows developers to expand its capabilities.

Audience

The second spiral reimplements Aktions based upon the discoveries made during the first spiral. It focuses upon specific usability tests. It may be used in any third-party software. This spiral is suggested for evaluation purposes only. Future iterations of Aktions will serve usability experts and KDE users.

General Constraints

License

All code developed for Aktions must be dual-licensed under both the GPL and LGPL license.

System

The system is a personal computer running the K Desktop Environment. It includes the desktop, task bars, windows, and any controls or widgets characteristic to that environment.

Functional Requirements

Application Programming Interface (API)

Action

The API approaches usability from an action-oriented perspective. The basic type of data it stores is an action. Actions are associated with what a user does, not how they do it. (e.g. Bold text, not "click toolbar button"). Actions have the following characteristics:

Name
The action performed by a user. Examples: select text, save document, undo
Method
The way a user perfomed the action. Examples: toolbar button, context menu, keyboard accelerator.
Application
The application that the action occured in. Examples: KWord, Konqueror, Konsole
Time
The time that an action occurred. This characteristic is referenced in absolute time.
User
The user that performed an action.

Task

Tasks are used within Studies (detailed below) to logically segregate actions by goal of the user. Studies contain the following characteristics:

Name
A short description to a given task. Examples vary with use-case.
Description
Instructions to prompt the user, or a verbose description of the task.
Start time
The time when a user is told to start a task. This characteristic is referenced in absolute time.
List of Pause/Resume Times
A list of ordered pairs delimiting when a task was paused and resumed. This characteristic is referenced in absolute time.
Stop time
The time when a user completes or is told to stop a task. If a task stops with an incomplete pause/resume pair, the resume time of the pair should be set to the stop time of the task. This characteristic is referenced in absolute time.
Each task is associated with any actions that occur between its start and stop times, but not between any pause/resume pair.

Study

Studies are collections of a set of tasks and/or actions. They are used to define a set of data to analyze for a usability study. Studies have the following characteristics:

Name
The title of the usability study. Examples vary by author.
Description
An abstract which describes what the study proposes or hopes to discover. Descriptions may include hypotheses, procedures, authors, etc.
Start time
The time when the study begins. This characteristic is referenced in absolute time.
List of Pause/Resume Times
A list of ordered pairs delimiting when a study was paused and resumed. This list contains the elements of pause/resume lists of all tasks within the study. This characteristic is referenced in absolute time.
Stop time
The time when the study ends. If a study is stopped with an incomplete pause/resume pair, one of three actions occurs:
  • If the pause/resume pair is associated with a task, resolve the missing element per that task.
  • If the pause/resume pair is not associated with a task, and the study contains a task whose start time succeeds the pause time, then set the resume time to the start time of that task.
  • Otherwise, set the resume time equal to the stop time of the study.
This characteristic is referenced in absolute time.
Each study is associated with any actions that occur between its start and stop times, but not between any pause/resume pair.

Comment

Comments are miscellaneous notes that a user can add to a study or task. Comments have the following characteristics:

Text
The contents of a comment.
Time
The time the comment was added. This characteristic is referenced in absolute time.
Study or Task
The Study or Task this comment should be associated with. This characteristic is optional.

Data Collection

Aktions provides a means of accepting and storing Actions, Tasks, Studies, and Comments. Actions can be recieved from several programs concurrently, so the implementation must be thread-safe. The data collection mechanism includes hooks into the KDE libaries.

Data Retrieval

Aktions provides a means of retrieving Actions, Tasks, Studies, and Comments from storage. When an object is requested, all characteristics are be retrieved. Any data which is associated with that object requires a separate request.

Actions should be retrievable and filtered by one or more of the following key values:

Application
Retrieve all actions associated with a given application.
Study
Retrieve all actions associated with the given study. Does not group these actions by task. Results should be filtered according to the pause/resume list.
Task
Retrieve all actions associated with the given task. Results should be filtered according to the pause/resume list.
Time span
Retrieve all actions that ocurred between a given starting and ending time.
User
Retrieve all actions associated with the given user.

Tasks should be retrievable and filtered by one or more of the following key values:

Name
Retrieve all tasks that include the given name.
Study
Retrieve all tasks associated with the given study.
Time span
Retrieve all tasks that ocurred between a given starting and ending time.

Studies should be retrievable and filtered by one or more of the following key values:

Name
Retrieve all tasks taht include the given name.
Time span
Retrieve all actions that ocurred between a given starting and ending time.

Comments should be retrievable filtered by one or more of the following key values:

Study
Retrieve all comments associated with the given study. Does not group these actions by task.
Task
Retrieve all comments associated with the given task.
Time span
Retrieve all comments that ocurred between a given starting and ending time.

Administrative Console

Main Window Layout

The main window is comprised of 4 pieces:

Study and Task Pane
The study and task pane is a tree view located on the left side of the window.
Detail Pane
The detail pane is a tabbed view located on the right side of the window.
Menu Bar
The menu bar is located at the top of the window.
Tool Bar
The toolbar is initially located at the top of the window, directly below the menu bar. It can be moved to another location, or detached from the window while the Administrative Console is running.

Study and Task Pane

The study and task pane initially lists the studies stored by Aktions. When a user selects a study, the interface inserts an indented list directly beneath the selected study. The indented list contains all tasks and comments associated with the selected study. These entries are sorted by type (tasks then comments) and then by time. The interface also loads any study-related plugins into the detail pane. It pre-loads related information into those plugins, when such information is available. When a study is unselected, the interface stops displaying any related plugins. If another study is selected, the interface ceases to display the indented list of tasks and comments.

When a user selects a task, the interface inserts an indented list directly beneath the selected task. The indented list contains all comments associated with the selected study. These entries are sorted by time. The interface also loads any task-related plugins into the detail pane. It pre-loads related information into those plugins, when such information is available. When a task is unselected, the interface stops displaying any related plugins. If another task is selected, the interface ceases to display the indented list of tasks and comments. If a task ceases to be displayed by the interface, its indented list of comments cease as well.

The context menu provides the following management facilities:

Detail Pane

The detail pane consists of a set of tabs. Each tab displays the interface for a plugin. The detail pane uses KParts technology to load plugin modules into each tab.

The menu bar contains the following menus: file, tools, settings, help. The file menu contains: add study, "add task to...", "add comment to...", quit. The tools menu is only visible when plugins are loaded. It contains any features specific to the currently displayed plugin. The settings menu contains: "configure Aktions...", "configure plugins...", "configure shortcuts...", "configure toolbars...", and "configure administrative console...". The help menu contains what's this, "Aktions handbook...", "about Aktions...", and "about KDE...". Most of these options are standard items provided by the KDE libraries.

Tool Bar

The tool bar contains the following items by default: "new" combo button, filter data, print, and delete study/task/comment. The "new" combo button provides the following actions: add study, "add task to...", and "add comment to...".

Non-functional Requirements

Application Programming Interface

Qt-Style Interface

The Aktions API's functions are modeled in the Qt Style.

Adhere to KDE Library policy

The libraries provided by Aktions must adhere to the KDE Library Code Policy .

Performance Characteristics

Aktions cannot have a human-noticeable impact upon the performance of the system it monitors. Aktions is designed to run on interactive systems that must remain responsive at all times.

System Evolution

General Functionality

Application Programming Interface

Administrative Console

Appendix

Glossary

Absolute Time
Time indexed by Day/Month/Year Hour:Minute:Second notation, as opposed to the time relative to the last event. Days, months, and years are indexed via the gregorian calendar, albeit they may be stored differenetly.
Application Programming Interface (API)
the interface that a computer system or application provides in order to allow requests for service to be made of it by other computer programs, and/or to allow data to be exchanged between them .
Application Binary Interface (ABI)
describes the low-level interface between an application program and the operating system, between an application and its libraries, or between component parts of an application .
Information Repository
a construct capable of storing and retrieving information pertinent to Aktions. An information repository can range from a remote database to a local text file.

Footnotes

This document is located on the Aktions website. http://aktions.sf.net/requirements_document_spiral1.html.

For more information: Trolltech. Qt Libraries. http://www.trolltech.net/products/qt/index.html.

For more information: KDE Project. KDE Developer's Corner. http://developer.kde.org/.

For more informtation: Free Software Foundation. GNU General Public License. http://www.gnu.org/copyleft/gpl.html.

For more information: Free Software Foundation. GNU Lesser General Public License. http://www.gnu.org/copyleft/lgpl.html.

For more information: Wikipedia. K Desktop Environment. http://en.wikipedia.org/wiki/K_desktop_environment.

For more information: IBM. Coding with KParts. http://www-128.ibm.com/developerworks/library/l-kparts/.

For more information: KDE Project. KDE Wiki. http://wiki.kde.org/tiki-index.php?page=Qt+Style+APIs.

For more information: KDE Project. KDE Developer's Corner. http://developer.kde.org/policies/librarypolicy.html.

For more information: KDE Project. DCOP: Desktop COmmunications Protocol. http://developer.kde.org/documentation/other/dcop.html.

For more information: FreeDesktop.org. Software/dbus. http://www.freedesktop.org/wiki/Software/dbus.

For more information: Wikipedia. Application Programming Interface. http://en.wikipedia.org/wiki/Application_programming_interface.

For more information: Wikipedia. Application Binary Interface. http://en.wikipedia.org/wiki/Application_binary_interface.