FAQ System
part of the ArsDigita Community System
by David Hill
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 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 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