<html>
<!--AD_DND-->
<head>
<title>FAQ System</title>
</head>
<body bgcolor=#ffffff text=#000000>
<h2>FAQ System</h2>
part of the <a href="index.html">ArsDigita Community System</a>
by <a href="mailto:dh@arsdigita.com">David Hill</a>
<hr>
<ul>
<li>User directory: <a href="/faq/">/faq/</a>
<li>Site Administrator directory: <a href="/admin/faq/">/admin/faq/</a>
<li>Per-FAQ Administration directory: <a href="/faq/admin/">/faq/admin/</a>
<li>data model: <a href="/doc/sql/display-sql.tcl?url=/doc/sql/faq.sql">/doc/sql/faq.sql</a> (also see subsection within)
<li>procedures: in tcl/faq-defs.tcl
</ul>
<h3>The Big Picture</h3>
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.
<P>
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.
<h3>The Medium-Sized Picture</h3>
This system consists of only two simple tables. And for FAQ maintainance the new group and scoping system is used.
<P>
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.
<blockquote>
<pre>
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'))
);
</pre>
</blockquote>
<P>
The body of a FAQ (questions and answers) are held in the faq_q_and_a table.
<blockquote>
<pre>
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
);
</pre>
</blockquote>
<h3>Legal Transactions</h3>
From the Site Administration pages at <a href="/admin/faq">/admin/faq</a> the site-wide administrator can
<ul>
<li>Create a new FAQ: insert a new row in the table faqs
<li>Edit the properties of a faq: update a row in the table faqs
<li>Delete a faq: delete from faq_q_and_a where faq_id=**faq_id** then delete from faqs where faq_id = **faq_id**
<li>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.
</ul>
<P>
From the Maintainers admin pages at <a href="/faq/admin">/faq/admin</a> or
/groups/admin/**X**/faq/ the FAQ maintainers can
<ul>
<li>Add a FAQ (for this group)
<li>Edit a FAQ (for this group)
<li>Delete a FAQ (for this group)
<li>Add content to a FAQ: insert a new row in faq_q_and_a
<li>Edit content in a FAQ: update a row in faq_q_and_a
<li>Reorder content in a FAQ: update sort_keys in faq_q_and_a
<li>Delete content from a FAQ: delete a row from faq_q_and_a
</ul>
<h3>Acceptance Test</h3>
<ul>
<li>As site-wide admin:
<ul>
<li>Go to /admin/faq/
<li>Create a public FAQ
<li>Create a private FAQ for Group X
<ul>
<li>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.
</ul>
<li>Visit /faq/ and click on the public faq
<li>Click on Maintain this FAQ
<li>Add questions, edit questions, swap questions, insert after..
<li>Edit the FAQ name
</ul>
<li>As a simple user:
<ul>
<li>Go to /faq/
<li>Visit the public FAQ
</ul>
<li>As an administrator for Group X
<ul>
<li>Visit /groups/X/faq/
<li>Perform the same tests on the private FAQ that you did on the public one
</ul>
</ul>
<h3>Future Improvements</h3>
<ul>
<li>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.
<li>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.
<li>A restorable audit trail of changes made to a FAQ would also be nice
</ul>
<hr>
<a href=mailto:dh@arsdigita.com><address>dh@arsdigita.com</address></a>
</body>
</html>