TravelPub Software Requirements
v1.0 alpha 2.

Introduction

General

This specification describes the requirements for the TravelPub software. TravelPub is a software system that maintains an on-line, configurable, user-contribution maintained travel guide. This provides a tremendous improvement over the standard, book-based, guides in that an on-line guide is always up-to-date, is tailored to individual users' travel tastes, and provides reviews that are based on several peoples' opinions rather than that of a single author.

A Word About Format

This document presents the requirements in a way similar to the old defense contractor documents. Each item that is required is introduced with the word "shall" and is numbered in square brackets. Additionally, some requirements have sub-requirements; these are listed in unnumbered lists but marked with letters in parenthesis. An example of this would look like:

The software shall [3] do a bunch of stuff including:

Those sub-requirements would be referred to as requirements 3a and 3b.

Please don't get all freaked-out by the formality of numbered "shall"s. Some cool things about this system include making the requirements document clearer and making testing easier (if you cover each of the numbered items, you're done). And there's nothing that says that this document can't be modified as the design/development team determines that different things need to be addressed.

This document is not intended to address design choices. Still, the document authors will have some ideas in this regard while they're developing this document. Those ideas may be placed in a box:

NOTE: design ideas may be included in boxes like this one.

These ideas are not requirements and should not constrain the design team in their choices. They are just meant to allow the requirements writers to have a place to include ideas.

Versioning

Not all of these requirements need to be addressed in the first implementation of this software. Some Clients may not be present, for example, at the time that TravelPub is launched. The requirements should be taken into account, however, in the design of the software. Restated: some of these requirements may find their way into a second (or third, or ...) version of TravelPub.

Concept of Execution

TravelPub is intended to be an on-line, user-maintained travel guide.

The TravelPub Server contains information on an array of cities in a variety of countries. Each user has a unique identity on the Server so a user has to log into the Server before doing anything. After login, the user enters requests that, when combined with the user's preferences, produce an Itinerary for the TravelPub Client. The Client, then, acts as a travel guide that has been tailored to the tastes and requested locations of the user.

While the user is traveling, he updates the information that's on the Client. The next time the Client is connected to the Server, the Client updates the Server with the information that has changed. The Server then incorporates the updated information, combined with the User's Reliability Rating (a score derived from the user's previous activity on TravelPub), to provide information to other users.

Each user's Reliability Rating is calculated from how well the User's update information agrees with other users' and other users' votes on the User's reliability.

Glossary

The following terms will be used in the following requirements.

Requirements

General

Several interfaces in this document specify the World Wide Web (WWW) as an interface mechanism. As a goal, the WWW interfaces specified in this document will be able to be completely viewable by any web browser. At a minimum, any WWW interfaces specified in this document shall [] be web pages completely viewable by all of the following:

The TravelPub software shall [] be composed of the following pieces.

TravelPub Server

The TravelPub Server does the following:

It is anticipated that there will only be one TravelPub Server (though that Server may be distributed among several machines spread across several locations) at any one time. Even so, this specification does not require, or even assume, that only one Server will exist.

Location information

Once a user determines the cities and sites within those cities that he wishes to load onto his Client, the TravelPub Server will build an Itinerary to be downloaded. The TravelPub Server shall [] make available the following types of information about countries to be written to an Itinerary:

NOTE: we may team with some other website to incorporate exchange rate and, maybe weather. It also might be interesting to include links to the state department warning site.

The TravelPub Server shall [] make available the following types of information about cities to be written to an Itinerary:

NOTE: One way to handle city regions would be to make 'region' a required part of the country/city/region/site hierarchy. Cities with no region would actually have one called "the city". Similarly, countries could always have at least one country region (country regions could be used for states/provinces).

The TravelPub Server shall [] make available the following types of information about sites within a city to be written to an Itinerary:

Site types shall [] include:

Some site types will need to have additional information stored for them. Each site to which the information is applicable shall [] include:

NOTE: do we need a parent site 'class' and child site 'classes'? should we have a different fundamental type for bus stops/metro stops since there's so much less information for them?

NOTE: there should be a way to indicate whether a restaurant has non-salad all-vegie food and/or vegan food

Question: where do we get the definition of hotel star rating?

This information should be correlated with dates so sites that change hours or prices in the off-season are recorded properly.

A Site's Composite Rating shall [] be calculated based, at a minimum, on the following information:

Any single user shall [] have no more than one vote for a site counted toward a site's Site Composite Rating.

A Site's Composite Rating is a function of time since it is based on a value that changes over time (i.e., User Reliability Ratings). Each Site's Composite Rating shall [] be recalculated on a periodic basis (e.g., once a week).

NOTE: This implies that, at a minimum, the user number and the Site's Individual Rating must be saved for each vote made.

User information

One of the benefits of TravelPub is its generation of Site Composite Ratings. Because these values are based partially on the reliability of the users who make their recommendations (and because building Itineraries is made quicker by using user preferences), TravelPub will have to store at least some user information. TravelPub shall [] save the following information for each user:

We want to take user privacy seriously. TravelPub shall [] not provide any mechanism to allow non-administrators to extract more than username or User Reliability Rating from TravelPub.

NOTE: As a matter of policy, we shouldn't allow any administrator to reveal user information without the user's express written permission.

A user's username and password should be user-selectible. The rules associated with TravelPub shall [] prohibit a user from having more than one username.

NOTE: The User's email address would make an excellent password. Also, users' passwords may be stored encrypted.

The User Reliability Rating will be based on several criteria, possibly including:

TravelPub Server User Interface

The TravelPub Server will build an Iternarary based on user input, user preferences, and (of course) the information stored in the TravePub Server. The Itinerary generation software shall [] use a series of world wide web pages as a user interface mechanism.

User Sign-Up

User sign-up is the process where a user creates his TravelPub account. Each user must sign-up once before using TravelPub. Because intended users are expected to vary in computer proficiency from novice to expert, the sign-up page should be the least intimidating interface we can muster. The TravelPub sign-up page shall [] require no more than 7 inputs. The user interface will probably have the following inputs:

Travel profile is a simplified mechanism for describing how the user travels. I would imagine that there will be about five profiles, for example:

Each profile would provide a complete set of default values for the user's preferences. The user could choose, thereafter, to modify his preferences to fine tune them.

User Preferences

TravelPub's user preference information should be rich enough to allow many (most?) users the ability to login, add all pertinent cities to their Itinerary, and download it (as per the user's preferences) to the TravelPub Client. The sign-up options should be simple enough but, at the same time, general enough that most user's can select a profile and the resultant preference choices allow most user's to create a good Itinerary with almost no input. The user preference information shall [] include:

NOTE: We should probably also have a preference for "reselect defaults based on a travel profile."

Building an Itinerary

Most of a user's interface with the TravelPub Server will be spent building an Itinerary. The TravelPub Server shall [] provide an interface to the user to allow him to create an Itinerary. At a minimum, the TravelPub Server shall [] support the following operations during Itinerary building:

The normal workflow for editing city information will be something like:

QUESTION: Should this workflow be a requirement? The points of interest should always go first, I would think.

When building an Itinerary, the TravelPub Server shall [] display sites of different types under separate headings. All site types that have a non-zero preference setting for number of sites of this type to include shall [] be displayed to the user. All sites that are listed by the TravelPub Server shall [] be sorted in order of Site Composite Rating. For each site type, the highest ranked number of sites to include as specified by the user's preferences shall [] be auto-selected. Each site shall [] be able to be individually selected and de-selected by the user. All selected sites shall [] be included for the city when the Itinerary is written to a Client.

The top-level Itinerary building interface shall [] include a button labeled "splurge". That button shall [] raise the price restrictions to the next level for all of the site types for this trip. The interface for each site type shall [] include a button labeled "splurge". That button shall [] raise the price restrictions for this site-type to the next level for this trip.

The top-level Itinerary building interface shall [] include a button labeled "shoestring". That button shall [] lower the price restrictions down to the next level for all of the site types for this trip. The interface for each site type shall [] include a button labeled "shoestring". That button shall [] lower the price restrictions for this site-type down to the next level for this trip.

Points Of Interest. The TravelPub Server shall [] list all of the points of interest in a city.

Hotels. The TravelPub Server shall [] list all hotels in a city that match the user's preferences. If the user's hotel location preference is site-based, hotels within the preference-specified distance from currently-selected sites shall [] be auto-selected first and shall [] be listed with the distance to the nearest currently-selected site. If the user's hotel location preference is city based, the top 'n' hotels (arranged by composite site rating) where 'n' is the user's preference for maximum number of hotels shall [] be auto-selected.

Sites and Restaurants. The TravelPub Server will provide an interface for picking sites for an Itinerary based on the Client layout preference in the user's preferences.

For traditional Client layouts, the TravelPub software shall [] list all sites in the city. For each site type, the highest ranking sites equal to the user's preference for maximum number of this type to auto-select (or all of the sites of this type if the number of sites listed is less than the preference number) shall [] be auto-selected.

For site-based Client layouts, the TravelPub Server shall [] list all the hotel-based sites that are within the maximum distance specified in the user's preferences from each selected hotel and all point-of-interest-based sites that are within the maximum distance specified by the user's preferences. For each site type, if the number of sites shown is greater than or equal to the user's preference for maximum number of this type to auto-select, the highest ranking sites equal to this number shall [] be auto-selected. For each site type, if the number sites shown is less than than the user's preference for maximum number of this type to auto-select, additional sites shall [] be added in distance order until either the maximum number has been met or the number of sites of this type in this city has been exhausted; in either case, all of the sites shall [] be auto-selected.

Writing An Itinerary To A Client

Having an Itinerary on the Server is all well and good but it'll do a lot more for the user if he can take it with him. The TravelPub Server shall [] provide a user interface to ask the user which Client type the user wants to target. The user's default Client type, as listed in his preferences shall be [] automatically selected but the user shall [] be able to modify that selection.

The Server shall [], when the user requests it, build an Itinerary and, for Clients that require it, provide it to be downloaded to the Client.

The Itinerary will be built from the Server's information in such a way as to minimize false information [I'm not sure how to specify this as a requirement].

Reading An Updated Itinerary From A Client

The TravelPub Client can be used to either browse or modify an Itinerary. When an Itinerary is modified, the modified information is transferred back to the TravelPub Server to update the Server's location information. The Server shall [] provide a mechanism to transfer updated location information from the Client back to the Server. That information shall [] be incorporated into the Server's information store.

Updating Location Information

The TravelPub Server shall [] be able to update any piece of location information it has stored from the Client. Moreover, the Server shall [] be able to add new information from the Client. The Server shall not [] delete information based on Client information (though it may mark Server information as invalid). All information added to the Server (or changed on the Server) shall [] be accompanied by a valid user identifier.

Updating User Information

The TravelPub Server shall [] provide a user interface to allow a user to update all fields regarding him in the User Database except his User's Reliability Rating.

TravelPub Client

At a minimum, TravelPub shall [] support the following types of Clients:

There's a bunch of things you'll want to be able to do with the TravelPub Client. Some of the Client types won't be able to handle all the capabilities but they're all listed, here, for completeness. Clients that are hosted on a computer are termed reconfigurable Clients (there's some question about whether html clients will be reconfigurable or static in nature).

Display Data

You'll want to display data on the Client. TravelPub Clients shall [] provide separate displays for main, country, and city information. The main display shall [] contain a list of available countries. For reconfigurable Clients, the main display shall [] allow navigation to every available country and each country display shall [] allow navigation back to the main display. Each country display shall [] contain a list of available cities in that country. For reconfigurable Clients, each country display shall [] allow navigation to every available city in that country and each city display shall [] allow navigation back to its country display.

A TravelPub Client shall [] support both text display and map display.

Text Display

Non-reconfigurable Clients shall [] display all available information about each site. At a minimum, reconfigurable Clients shall [] display for all sites, the following

.

At a minimum, a TravelPub Client shall [] support a traditional arrangement and a site-based arrangement of city data. Clients that aren't reconfigurable need to support a choice at initial configuration (sometimes, this will be controlled by the Itinerary-generation software).

Traditional Arrangement. When a Client displays text in a traditional arrangement, each listed site shall [] be listed under a heading that matches its own site type. At a minimum Clients shall [] support the following order of site types:

Reconfigurable Clients may choose to allow the user to select other site type orders.

Site-Based Arrangement. The point of a arranging sites this way is to organize things the way the traveller navigates a city. When a traveler wants to go to a top-level site (e.g., hotels or points-of-interest), it doesn't matter where he is or where the site is -- he just wants to go there. When a traveller wants to go to sites like restaurants, however, he wants to go to one nearby. Sites like these are called subordinate sites. There's a third type of site, called an independent site, that's like a top-level site but has no subordinate sites associated with it (like post offices).

Hotels shall be [] top-level sites. For site-based Client layouts, the following shall [] be subordinate sites for (and will be listed underneath) each of the hotels in the layout:

Points of interest shall be [] top-level sites. For site-based Client layouts, the following shall [] be subordinate sites for (and will be listed underneath) each of the points of interest in the layout:

Some sites that are subordinate sites are also independently listed in the site-base layout. For site-based Client layouts, the following shall [] be independent sites:

NOTE: Should we make this configurable?

Map Display

We'll want the ability to display maps. For reconfigurable Clients, each map display shall [] be reachable from a text display and shall [] allow navigation back to their parent text display.

Search

Reconfigurable Clients shall [] provide the ability to search through the Itinerary. The search shall [] include the entire text of the Itinerary. Matches shall [] be presented, at a minimum, as a list of sites that, somewhere in the site information, matches the search. Clients shall [] support limiting searches to sites within a user-specified distance from a location or, where supported, a GPS location. Clients shall [] support limiting searches to certain site types.

Update

One of the really cool features of TravelPub is the ability of users to update the Itinerary on their Client and to have that informtion be incorporated into the TravelPub Server. (Note: all requirements in this section apply only to reconfigurable TravelPub Clients). Reconfigurable TravelPub Clients shall [] add a mark to stored Itinerary information for any information added to or modified in an Itinerary in the Client. That mark will be used by the TravelPub Server to know what has changed so that the Server can update its information.

The TravelPub Client shall [] provide an interface for adding (a) countries, (b) cities, and (c) sites to an Itinerary. New cities shall [] be associated with an existing country in the TravelPub data store. New sites shall [] be associated with an existing city in the TravelPub data store. The TravelPub Client shall [] provide an interface for changing existing information in an Itinerary. The TravelPub Client shall [] provide an interface for adding comments to an Itinerary.