ArsDigita Archives
 
 
   
 
spacer

FAQ Module Design

by Bryan Che

I. Essentials

II. Introduction

The FAQ module provides a system where administrators may create and maintain Frequently Asked Question (FAQ) pages for groups of users and where users may read FAQ's. A given FAQ can be either public and viewed by everyone or restricted so that only members of a given group may see the FAQ. This kind of system is inherently different from the BBoard system in that there are two distinct types of users -- those that can only read the FAQ and those who may contribute questions and answers.

III. Design Tradeoffs

One limitation of this FAQ design is that questions and answers are varchars rather than clobs. This imposes a 4000 character limit on individual questions and answers. It is possible that some FAQ maintainers may wish to write questions or answers which exceed this character limit. This will probably be a rare occurrence, though. Furthermore, using varchars rather than clobs makes writing, maintenance, and readability of the FAQ code far simpler.

IV. Data Model Discussion

This system consists of only two simple tables. And for FAQ maintainance the new group and scoping system is used.

The properties of a FAQ are held in the faqs table: These properties are the name of the faq and who can see the FAQ. 

create table faqs (
	faq_id		integer primary key,
	-- name of the FAQ.
	faq_name	varchar(250) not null,
	-- group the viewing may be restriced to 
	group_id	integer references user_groups,
	-- permissions can be expanded to be more complex later
        scope		varchar(20),
        -- insure consistant state 
       	constraint faq_scope_check check ((scope='group' and group_id is not null) 
                                          or (scope='public'))
);
The body of a FAQ (questions and answers) are held in the faq_q_and_a table. 
create table faq_q_and_a (
	entry_id	integer primary key,
	-- which FAQ
	faq_id		integer references faqs not null,
	question	varchar(4000) not null,
	answer		varchar(4000) not null,
        -- determines the order of questions in a FAQ
	sort_key	integer not null
);

V. Legal Transactions

From the Site Administration pages at /admin/faq the site-wide administrator can
  • Create a new FAQ: insert a new row in the table faqs
  • Edit the properties of a faq: update a row in the table faqs
  • Delete a faq: delete from faq_q_and_a where faq_id=**faq_id** then delete from faqs where faq_id = **faq_id**
  • Assign group **X** to the FAQ: The FAQ system must be associated with the group_type for group **X**. An administrator for group **X** will be able to administer the FAQ and only members of group **X** will be able to view the FAQ.

From the Maintainers admin pages at /faq/admin or/groups/admin/**X**/faq/ the FAQ maintainers can

  • Add a FAQ (for this group)
  • Edit a FAQ (for this group)
  • Delete a FAQ (for this group)
  • Add content to a FAQ: insert a new row in faq_q_and_a
  • Edit content in a FAQ: update a row in faq_q_and_a
  • Reorder content in a FAQ: update sort_keys in faq_q_and_a
  • Delete content from a FAQ: delete a row from faq_q_and_a

VI. API

The FAQ module provides the following scripting (TCL) procedures which developers might find useful:

faq_authorize { faq_id } : given faq_id, this procedure will check whether the user can the right to see this faq. if faq doesn't exist page is served to the user informing him that the page doesn't exist. if successfule it will return user_id of the administrator.

faq_admin_authorize { faq_id }: given faq_id, this procedure will check whether the user can administer this faq (check whether the user is group administrator). if faq doesn't exist page is served to the user informing him that the page doesn't exist. if successfull it will return user_id of the administrator.

faq_maintaner_p { faq_id }: checks whether the user has the right to mantain this faq

VII. User Interface

The Site-wide Administrator Interface

The administrator may create, maintain, or delete all FAQ's on his Web site from the site-wide administration directory.

The Sub-site-wide Administrator Interface

The sub-admin may create, maintain, or delete all FAQ's for his sub-site (user group).

The User Interface

The user may only read FAQ's. And, he may only read public FAQ's and FAQ's belonging to user groups of which he is a member.

VIII. Acceptance Test

  • As site-wide admin:
    • Go to /admin/faq/
    • Create a public FAQ
    • Create a private FAQ for Group X
      • Visit /admin/ug/index and make sure that the group_type of which group X is a member is associated with the FAQ module.
    • Visit /faq/ and click on the public faq
    • Click on Maintain this FAQ
    • Add questions, edit questions, swap questions, insert after..
    • Edit the FAQ name
  • As a simple user:
    • Go to /faq/
    • Visit the public FAQ
  • As an administrator for Group X
    • Visit /groups/X/faq/
    • Perform the same tests on the private FAQ that you did on the public one

IX. Future Improvements

  • The ablility to have questions and answers appear on separate pages, so that a FAQ could have a page which just lists questions. Each question would link to a page with just the one question (repeated) and the answer on it. This would be necessary for a very large FAQ. The current FAQ page simply uses anchors to link to questions.
  • Currently all questions and answers are assumed to be html when posted by a FAQ maintainer; the option of html/text would be nice here.
  • A restorable audit trail of changes made to a FAQ would also be nice

X. Authors

bryanche@arsdigita.com
spacer