FAQ System

part of the ArsDigita Community System by David Hill

User directory: /faq/
Site Administrator directory: /admin/faq/
Per-FAQ Administration directory: /faq/admin/
data model: /doc/sql/faq.sql (also see subsection within)
procedures: in tcl/faq-defs.tcl

The Big Picture

Many sites have a page or series of pages to answer Frequently Asked Questions (FAQ). We want a simple interface for creating and maintaining FAQs in which the work of FAQ maintainance may be shared by specific people. A given FAQ can be either puplic 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.

The Medium-Sized Picture

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
);

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

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.tcl 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

Future Improvements

The ablility to have questions and answers appear on separate pages, so that one-faq.tcl could just be the list of questions that each 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 just 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

dh@arsdigita.com