Classifieds Module Design
by Curtis Galloway
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
- 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
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
- Within reasonable bounds, what this system is not intended to allow the system user to
- 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.
Scalable Systems for Online Communities
Philip and Alex's Guide to Web Publishing, and
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
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
- 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
- Any considerations pertinent to that particular data
model and ensuring table integrity should be highlighted at this
- 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.
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:
- transactions, and
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
IX. User Interface
This section should offer a discussion of any user interface
considerations relevant to each of the three classes of intended
- Site-wide administrators
- Sub-site administrators
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
- Reliability and robustness
Areas of interest to developers:
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?"
; SystemOwner= (defaults to global system owner)
; send a reminder to people to edit or delete their ads?
; some stuff to deal with annoying photo.net abusers
; don't let people put the word "reduced" in subject line
XI. Acceptance Tests
You should test setting up a domain, posting/editing and ad, alerts, hot auctions and searching.
- 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
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