Classifieds Module Design

I. Essentials

User directory: /gc/
Moderators' directory: /gc/admin/
Sitewide administrator directory: /admin/gc/
Data model : /arsdigita/doc/sql/classifieds.sql
Tcl procs: /tcl/gc-defs
Requirements document: /arsdigita/doc/requirements/classifieds
Page Flow: /arsdigita/doc/page-flow/classifieds_interaction_admin.pdf and /arsdigita/doc/page-flow/classifieds_interaction_users.pdf
ER diagram: /arsdigita/doc/er-diagrams/small_classifieds_er.pdf

II. Introduction

The classifieds module provides a mechanism for posting user-contributed content that may be categorized, and which is unrelated to static content. In the most common case, it can be used for advertisements in the form of newspaper classified ads. Items can also be offered in an auction format, where users bid successively higher prices until the auction closes.

However, the classifieds module could also be adapted for the following applications:

a personal ad service with five categories: men seeking women, women seeking men, men seeking men, women seeking women, other.
a big company's "jobs available" page where the public could view all the listings but only existing employees would be able to post
scientists posting descriptions of their work; categorization would be by conference

The classified ad system has been in use at photo.net since 1996 and has processed over 100,000 ads.

What this system is supposed to allow the system user to accomplish.
Within reasonable bounds, what this system is not intended to allow the system user to accomplish.
In which sort of applications this system is most likely to be of use.
A high-level overview of how the system meets the design requirements. This is to include relevant material from the "features" section of the cover sheet.

Also worthy of treatment in this section are the following issues:

When applicable, a careful demarcation between the functionality of this system and other systems which at least superficially appear to address the same requirements.

Note that it is entirely possible that a discussion of what a system is not intended to do might differ from a discussion of future improvements from which the system might benefit.

See Chapter 3: Scalable Systems for Online Communities from Philip and Alex's Guide to Web Publishing, and Chapter 13 of How to be a Web Whore Just Like Me by Philip Greenspun for more detail.

III. Historical Considerations

When designing a software solution to meet the constraints of a fixed set of design requirements, it is almost always the case that many possible mutually exclusive solutions are given consideration. Although eventually only one solution is implemented, a discussion of those alternative solutions canvassed during the software design process, with special attention paid to the reasons for which these alternative solutions were rejected, should ultimately prove quite helpful to future developers and will help ensure that no time is wasted on the analysis of problems already solved.

IV. Competitive Analysis

Although currently only a few system documentation pages contain a discussion of the features of software which competes with the ACS system at issue (e.g., chat, portals), this should be an essential feature of the documentation for any system for which there exists competing software.

If the system exhibits features missing from competing software, this fact should be underscored.
If the system lacks features which are present in competing software, the reasons for this should be discussed here; our sales team needs to be prepared to handle inquiries regarding features our systems lack.

Note that such a discussion need not be coextensive with a discussion of a system's potential future improvements.

V. Design Tradeoffs

No single design solution can optimize every desirable system attribute. For example, an increase in the security of a system will entail a decrease in the simplicity of the system interface, and an increase in a the flexibility of a system typically entails a decrease in the simplicity of the structure of that system. As a result, a developer must decide to put a higher value on some attributes over others. This section should include a discussion of the tradeoffs involved with the design chosen and the reasons for this choice. Some areas of importance to keep in mind are:

VI. Data Model Discussion

The data model discussion should do more than merely display the SQL code for creating the relevant tables and sequences; this information should already be readily accessible via a link in the "essentials" section of the documentation. The discussion should constitute a high-level treatment of the primary entitites and main transactions relevant to the data model.

The data model discussion should address the intended content of each table column when this information is not perspicuous from an inspection of the data model itself.
Block copies from the data model should only be done adjacent to a discussion of the particular constraints imposed upon the data structure by that portion of the data model.
If an auxiliary system is being employed for table maintenance (e.g., the new group and scoping system, general comments, et cetera), this should also be mentioned.
Any default permissions should be identified herein.
If the data model contains extensions which can tie into other systems, this should be discussed here.

VII. Legal Transactions

This section should include a discussion satisfying each each of the following points:

Any modifications which the database may undergo as a result of employing the system under consideration should be discussed here.
Any considerations pertinent to that particular data model and ensuring table integrity should be highlighted at this point.
Legal transactions should be grouped according to the location of the files which perform the relevant data modifications, e.g., separate treatments for those data modifications which can be performed from the /admin pages for the system and those which can be performed by an ordinary community user on a system employing that system.

VIII. API

This section should include a discussion of the particulars of the database API used to provide an abstraction barrier between the system code and the underlying core software, typically so as to help minimize unnecessary repetition in the system code. Although this information may be covered in more general detail in other sections of this document, this section is the appropriate place to discuss the details of each of the procs employed in the development of this system, including each of:

algorithms,
transactions, and
UI.

Historically, the relevant procs have been encapsulated in a TCL file, however the current engineering effort encourages developers to avoid this practice. Also noteworthy is that although the ACS currently utilizes the AOLserver Tcl API, the current drive towards Java is likely to effect a change in the content of these sections in future instantiations.

IX. User Interface

This section should offer a discussion of any user interface considerations relevant to each of the three classes of intended system users:

Developers
Site-wide administrators
Sub-site administrators
User

In order that developer documentation be uniform across different system documents, these users should herein be designated as "the developer", "the administrator", "the sub-admin", and "the user", respectively.

Note that as our templating system becomes more robustly entrenched within the ACS, the details within this section are likely to shift from UI specifics to template interface specifics. Areas of interest to users:

Performance: availability and efficiency
Flexibility
Interoperability
Reliability and robustness
Usability

Areas of interest to developers:

Maintainability
Portability
Reusability
Testability

X. Configuration/Parameters

Via the ad.ini file, you can enforce a lot of publishing decisions, e.g., "don't allow anyone to mention eBay" or "how many bids does an ad have to get in order to be considered a hot auction?"


[ns/server/yourservername/acs/gc]
SystemName=Classifieds
; SystemOwner=  (defaults to global system owner)
PartialUrlStub=/gc/
ProvideLocalSearchP=1
ProvideEmailAlerts=1
; send a reminder to people to edit or delete their ads?
NagAdOwners=1
HowManyRecentAdsToDisplay=5
HotAuctionThreshold=2
; some stuff to deal with annoying photo.net abusers
; don't let people put the word "reduced" in subject line
DisallowReducedInSubject=1
DisallowExclamationPointInSubject=1
DisallowAllUppercase=1
DisalloweBay=1
IncludeBannerIdeasP=1
IndexPageDecorationTop=
IndexPageDecorationSide=
DomainTopDecorationTop=
HotAuctionsDecoration=
PlaceAdDecoration=
PlaceAd2Decoration=
EditAd2Decoration=
AddAlertDecoration=

XI. Acceptance Tests

You should test setting up a domain, posting/editing and ad, alerts, hot auctions and searching.
Suggested Method:

Go to /admin/gc and create a domain. Make sure you add a least one category.
Go to /gc and add an instant alert.
Post an ad.
Edit your ad.
Place a bid on the ad.
Search for your ad.
Deactivate your domain (you can leave it for later testing).

XII. Future Improvements/Areas of Likely Change

If the system lacks features which would be advantageous in the long-run, this should be noted here. Also noteworthy herein are ease-of-use considerations (e.g., UI and/or templating issues) not necessarily involving a system feature.

Note that a careful treatment of the earlier section entitled "competitive analysis" greatly facilitates the carrying out of the present section.

XIII. Authors

Although a system's data model file often contains this information, this does not hold true in general. Furthermore, data model files have often undergone substantial revision, making it difficult to track down the system creator from this information. Complicating matters, system documentation occasionally is authored by people not directly involved in the system creation process. Regardless of whether or not system ownership can be determined by appeal to these files, new system users should not be subjected to such a search simply in order to have access to some basic information about the history of system, such as system origin. Thus a mail link to the following should be included in each developer document:

System creator
System owner
Documentation author: Curtis Galloway

curtisg@arsdigita.com