Multiuser Bibliography Functional Requirements

This is a list of functional requirements for the Multiuser Bibliography application.

This document is subject to change. Version information:

Introduction

The Multiuser Bibliography application is a web-based interface to a repository of bibliographic information, citations for various types of resources with optional annotations. The application lets users collaborate on building a bibliography; it's intended to help small groups work together on research projects by letting group members make note of relevant resources as they encounter them. It's meant to be a simple, tightly-focussed, flexible solution to the task of recording resources, with minimal disruption to a researcher's normal workflow.

Here I have outlined functional requirements for the application in a number of areas. This is intended primarily to serve as a guide while developing the application, but it's also useful as part of the system documentation. During initial development, designers and developers should refer to this document to ensure that these requirements are satisfied. Afterwards, these requirements can be useful in various ways for system administrators looking to deploy the application (particularly the hardware and software requirements), maintenance developers who need to correct bugs or add new features, and possibly to potential users who are considering whether to use the application.

Application Requirements and Considerations

Requirements here are grouped broadly by functional area. Of course many requirements cross areas, so this should be regarded as no more than an organizational convenience.

The section headers below should be numbered. If they aren't, you're probably using IE6 or IE7. You should really try a better browser, such as Firefox.

Hardware Requirements

Multiuser Bibliography is a web-based server-side application. Processing is driven by form-based user input, so the transaction load is proportional to the number of active users, with substantial latency time between requests. The number of users is expected to be small. Consequently, commodity web server hardware should be sufficient, and the application can run on a shared or virtual server — a dedicated server should not be required.

Storage requirements are expected to be modest, as all data is entered manually by a relatively small number of users.

Software Requirements

Multiuser Bibliography requires a web server, PHP 5, and MySQL 5. It is otherwise platform-agnostic. The initial implementation will run on a Linux system under Tomcat, but any commercial web-server platform with PHP 5 and MySQL 5 support should work.

Functional Requirements

Functional requirements for the Multiuser Bibliography application, organized by task area. (This is taken directly from the Functional & Contents Requirements List document. It will be revised in a future version of this document.)

Access
  1. Anonymous limited access is available. Anonymous users have access to the search and browse functions.
  2. Full access to users with an active account is available via a sign-in process.
  3. The user's signed-in state should persist until they sign out or exit the browser, if the browser implementation and configuration permit.
  4. Users with administrator status also have access to administration functions once they sign in.
Viewing Entries
  1. All users can browse entries.
  2. All users can search for entries.
  3. Entries marked as "superseded" due to an edit are not shown in browse and search modes.
Adding Entries
  1. Signed-in users can add entries.
  2. Entries will have an auto-increment numerical ID as primary key, but they will also have a secondary key derived from the primary author, if supplied, or from the title. If no author or title is supplied, the secondary key may be derived from other data in the entry or may be defined in some other fashion.
  3. Input data should be sanitized to remove HTML markup. (This may not be implemented in the initial version, since only trusted users can enter data.)
Editing Entries
  1. Signed-in users can edit entries they created. Administrators can edit any entry.
  2. To avoid accidental loss of data due to editing accidents, submitting an edit will cause the old record to be marked as superseded, and a new record created. (There is no provision in the initial version of the application for recovering data from superseded records - that will have to be done manually. But at least it can be done.)
Annotating Entries
  1. Signed-in users can annotate (any) entries.
  2. Annotations are free-format plain text attached to entries.
  3. Annotations should be sanitized to remove HTML markup. (This may not be implemented in the initial version.)
Administration
In the initial version of the application, administration functions may be performed manually, rather than through application interfaces.
  1. Administrators will have access to functions to add and remove users, and to change user passwords.
  2. Administrators can edit any bibliography entry.
  3. Administrators can remove annotations.

Security Requirements

Multiuser Bibliography is not intended to store sensitive data. The nature of bibliographic information is to be published; usually, it already has been. Nor is bibliographic data typically a sensitive part of the research data for a project, since the original work is presumed to be in the analysis of the references and other data.

Portions of the application are only available to users, which means user authentication is required. Multiuser Bibliography, at least for its first release, will use simple username / password authentication with clear-text transmission of credentials. (Users will be warned to choose passwords unique to this application, due to the risk of compromise.) This risk is considered acceptable because the stored data is not sensitive and the application has very low visibility.

The user's authentication state is kept in a session cookie. The cookie can be removed via a sign-out process.

Database access credentials will be stored in the application, so if the server is compromised, the database may be as well. This risk is also considered acceptable, for the same reasons.

Interface Requirements

Functional requirements for the Multiuser Bibliography application, organized by task area. (This is based on the Functional & Contents Requirements List document. It will be revised in a future version of this document.)

Access
  1. A link to the sign-in page should appear in a header on every page if the user is not signed in. If the user is signed in, a sign-out (logoff) link should appear in its place.
Viewing Entries
  1. When browsing, entries are shown in secondary-key order. A number of entries (to be determined) are shown on each page. Browse-forward and browse-backward links are shown (but will be inactive if no more entries are available in the selected direction).
  2. When browsing, entries are shown in a condensed format similar to a generalized MLA "Works Cited" format. (Exact details of this format are still to be determined.) Search results are also shown in condensed format.
  3. The condensed format does not show the text of annotations, but entries with annotations will include a note to that effect, eg "(2 annotations)".
  4. Each condensed-format entry will have a link to its expanded-format view.
  5. In the expanded-format view, an individual entry is displayed. All fields are shown with labels, in tabular format. Annotations are displayed below the entry. Metadata such as the name of the user who added the entry and when it was added are displayed. Expanded-format views will have a link to the condensed view of the same entry; following that link returns the user to browse mode, so they can browse starting at that entry.
Adding Entries
  1. New entries are added by supplying bibliographic data such as author, title, etc, in a form, then submitting the form.
  2. No one field is required, since there is no one piece of bibliographic data common to all entries. (Some items do not specify authors, some are untitled, etc.) An addition is accepted if sufficient information is supplied to add it to the database. (Exact requirement to be determined when the database schema is finalized.)
  3. The form will include various fields to make it easy for users to add bibliographic details, such as "additional authors", "editors and translators", "additional publication information", etc.
  4. The form will also have a catch-all field for any information that does not fit the above categories.
  5. There will be a radio-button control to optionally specify the resource type, which can be used by the application to format titles, for example. It will include common types such as "book" and "article", an "other" catch-all, and "unspecified", which will be the default.
Editing Entries
  1. Editing is performed using the same form used for adding, populated with the existing details of the entry.

Database Requirements

Multiuser Bibliography uses a single normalized database for each bibliography, with the following tables:

Note that the application currently does not try to solve the citation-normalization problem — that is, it doesn't try to detect when entries refer to the same document. If it did, a separate unique-entry table would be required to maintain normal form.

Challenges / Opportunities / Benefits

Challenges:

Opportunities:

Benefits:

Testing Considerations

As with any application that uses persistent storage, testing will require a base-state database that can be restored at the start of each testing cycle.

Some automated testing can be done by driving the backend directly. Additional testing could be automated with a scriptable user agent that posts data to the application and verifies responses. Also, existing user agents such as Internet Explorer can be driven by OLE-based "screen scraping", to automate testing the actual user experience. However, due to resource availability, it's likely that testing will be largely manual for the first version.

No provision is made in the first version of the application to prevent simultaneous edits to the same entry. Testing should take that into account, by avoiding simultaneous edits for tests that should pass. It would also be good to have a simultaneous-edit test that currently fails, following Test-Driven Development practices, to document this limitation and serve as a regression test when it is corrected.

Performance Requirements

The application, in the initial release, is only intended to support a small number of users — perhaps two to four. Also, as noted above, this is an interactive application with extensive "think time" for users between small requests. Thus performance requirements are minimal, and should easily be satisfied by existing commercial servers.

The requirements categories used above were suggested by Michael McLeod.