[ZDP] The FAQ and the donkey

[Pavlos Christoforou]

[warning: long]

On Thu, 11 Mar 1999, Martijn Faassen wrote:

> Perhaps with your second design you could try to open the development
> process somewhat and focus on making it fairly easy to install for
> people and extend it? I for one would like to
> try to contribute.

Ok how about I give access to everyone interested to the administration
pages of the FAQ. You can use sessions to make changes, or actually you
can do anything you fancy. It is a work in progress. Lets see what a bunch
of people meddling together can create. Then we can say that the
collaborative FAQ has been collaboratively developed using Zope ;-)

>     CoolFAQ stands for Collaborative FAQ.
> 

Settled

> 
> Yes.
> 
> Perhaps Author should be 'contributor'. The ability to list multiple
[snip]
> wrong). There should of course be global editors too. Therefore, at
> least to 'section' we need a list of editors added. 'latest edit'
> timestamp would be good too.

We are thinking along the same lines. See my comments at the end.

> 
> Also, perhaps an ability to turn off comments on certain sections, or
> turn off global visibility of comments, at least. This isn't a big deal
> for FAQs like Zope's, but if this tool is going to be used for instance
> in an Intranet site, this might be desired.

This will be part of the DTML scripts. 

I do not think that the FAQ should
be a Zope product. It should be a bunch of DTML's plus a couple of
external methods. The *base* of the FAQ will be a hierarchy of folders
that correspond to sections,questions etc. That is why we need to decide
on a proper structure from the begining. Once we have that then the
presentation options and additional features are a matter of adding the
appropriate DTMLs

> 
> Well, there's output abilities, for instance in Docbook SGML/XML, or
> preconverted stuff (postscript, plaintext, anything). But with your XML
> system that can be added later without pain; the whole collaboration
> facility + a good web output system is what's necessary now.

Agreed

The Zope FAQ

The first step is to design an appropriate DTD for the
FAQ which should take into consideration features or
constrains imposed by the Zope system. The main reason
for using XML is to provide a relatively clear and easy
method to structure the FAQ entries. The aim is to
create a decent Zope FAQ application and **not** a
general XML FAQ application. Nevertheless a structured
approach is neccessary from the beginning as eventually
(hopefully) the FAQ will migrate to the DocBook format.

The FAQ will be divided into sections and each section
will contain a number of questions with their
corresponding answers. Each question can have only one
answer but they can both have any number of
comments. Questions answers and comments can have the
following optional attributes:

- *format* which denotes the format of the
 text. Currently supported formats are
 structured-text, html-quote and plain.

- *email* Contributor's e-mail address

- *contributor* Contributor's name

- *date* Submission date (Usually it will be entered by
   the application)

The default formats will be html-quote for the
questions and structured-text for answers and comments.


The parsing code for the DTD should be relatively easy
:-).  More important, XML FAQ entries should not be
complicated. Here I assume that comments to questions
and answers will mainly be submitted through the web
interface whereas whole FAQ entries or answers to
questions will probably be written in the contributor's
favorite editor. A complete FAQ entry might look like
this::

 <faq title='Zope FAQ'>
  <info>
   <version>0.2</version>
   <maintainer>Martijn Faassen</maintainer>
   <email>martijn@martijn.org</email>
   <date>11/3/99</date>
  </info>

  <section title='DTML'>
   <info>
    <maintainer>Martijn Pieters</maintainer>
    <email>theothermartijn@martijn.org</email>
    <date>11/3/99</date>
   </info>
   <entry>
    <question contributor='Jim'
   email='jim@jim.org'>
   How can you do this?</question>
    <question_comment>What a profound question</question_comment>
    <answer contributor='My cat'>Because</answer>
    <answer_comment>Now you are getting on my nerves</answer_comment>
    <answer_comment contributor='My cat' date='11/3/99'>
    More silly comments</answer_comment> 
   </entry>
  </section>
 </faq>

The <question_comment> and <answer_comment> look ugly
but I believe they will rarely be used as shown
above. The usual way to enter a comment or an answer is
through the web interface, so contributors will not
have to deal with all this verbosity.

The numbering of the FAQ entries will be determined by
the order of the sections and their entries in the XML
document. This is not a 'proper' procedure, but
including indexes as attributes of entries will limit
the dynamic nature of the FAQ tool. (Unless someone can
suggest an alternative).

Required also is an XML import/export facility.   

I don't thing the FAQ should be a Zope product. It
should be a bunch of DTML's plus a couple of external
methods. The *base* of the FAQ will be a hierarchy of
folders that correspond to sections,questions etc. That
is why we need to decide on a proper structure from the
begining. Once we have that then the presentation
options and additional features are a matter of adding
the appropriate DTMLs

For instance we can have a number of viewing options for our
FAQ. A simple plain one, a full version that includes comments
contributor info etc, a tree version similar to Amos etc. 

On the side margin I would like to have filtering
options. For instance when someone selects the 'last
week' option then subsequent actions should limit their
scope only on entries that have been submitted during
the past week. I have some ideas of how to go about it
but I would appreciate any feedback.

FAQ versions would be simply stored in different
Folders and the current one will be indicated by a
boolean property 'current'. Versions would also be
exported and backed up as xml documents.

The FAQ DTD follows. Please send comments on the DTD as
it represents the entire structure of the FAQ and it
would be difficult to change at a later stage. If you
are not familiar with DTD's then look at the example
entry above. It captures most of the DTD options.

<!ELEMENT faq        (info?,section+)>

<!ELEMENT info       (version?,author,email,date?)>
<!ELEMENT version    (#PCDATA)>
<!ELEMENT maintainer (#PCDATA)>
<!ELEMENT email      (#PCDATA)>
<!ELEMENT date       (#PCDATA)>

<!ELEMENT section    (info?,entry+)>
<!ELEMENT entry      (question,answer?,(qcomment|acomment)*)>
<!ELEMENT question   (#PCDATA)>
<!ELEMENT answer     (#PCDATA)>  
<!ELEMENT qcomment   (#PCDATA)>
<!ELEMENT acomment   (#PCDATA)>

<!ATTLIST faq        title  CDATA #REQUIRED>

<!ATTLIST section    title  CDATA #REQUIRED>

<!ATTLIST question   format CDATA "html-quote"
      author   CDATA #IMPLIED
      email    CDATA #IMPLIED
      date     CDATA #IMPLIED>
<!ATTLIST answer     format CDATA "structured-text"
      author   CDATA #IMPLIED
      email    CDATA #IMPLIED
      date     CDATA #IMPLIED>    
<!ATTLIST qcomment   format CDATA "structured-text"
      author   CDATA #IMPLIED
      email    CDATA #IMPLIED
      date     CDATA #IMPLIED>    
<!ATTLIST acomment   format CDATA "structured-text"
      author   CDATA #IMPLIED
      email    CDATA #IMPLIED
      date     CDATA #IMPLIED>
      date     CDATA #IMPLIED>

Pavlos