CoolFAQ Design

Design by the ZDP group

Document by Rik Hoekstra

With some heavy editing by Martijn Faassen

Intent

This document is not set in stone; the idea is for it to be a starting point for CoolFAQ. The document consists more or less of a set of snippets and is not as structured as it could be, yet. It may not even be entirely consistent.

Design issues

• A FAQ has an info part and section parts. Section parts have an info part and entry parts.

• An info part contains information about the FAQ, like title, version etc and any number of maintainers (or editors). In order words, metadata.

• Sections also have an info part and can have different maintainers.

• Entries have a question and answer pair and each can contain any number of contributors and comments.

• We need a way to represent the order of sections and entries in the different views on the CoolFAQ contents.

Exploiting Zope

Hierarchical structure is nice because it maps directly onto Zope's object system. It was Zope's object model that influenced the design. The FAQ tool is intented to be collaborative, and a hierarchical structure makes it easy to delegate permissions and responsibilities to different maintaine

Although we intend to make a separate Zope-based web interface for CoolFAQ, Zope's standard GUI can always be used to modify the contents of CoolFAQ as well.

Using XML

Representing the contents of CoolFAQ in XML helps us to design CoolFAQ's data structure more clearly and umambigeously (note: look at RDF?). XML will also help with importing and exporting of data to the CoolFAQ server, and general interoperability. At a later stage, for instance, XML will help with easy conversion to other formats, such as for instance DocBook.

An XML FAQ doc is composed of entries alone, and subelements of the entries indicate the section, subsection etc that the entry belongs to.

An XML doc can be read into the CoolFAQ and converted into a hierarchy of Folders with appropriate properties. Given the verbosity of the XML doc the prefered way of adding new entries, answers and comments will be through the web, by using appropriate DTML methods.

Using ZTables

ZTables will be used to represent the data and metadata in the Zope database. ZTables allows the creation of different views on this data.

Data and metadata

CoolFAQ should allow collaboration and review of proposed questions and answers (and comments).

A question/answer pair has a set of characteristics:

• Question (one question)

  • Text

  • Author information

  • Creation/edit dates

• Answer (zero or none official answers)

  • Text

  • Author information

  • Creation/edit dates

• Comments (multiple)

  • Text

  • Author information

  • Creation/edit dates

  Possibly comments specifically for question and answers, though this may not be necessary; comments are generally about questions, and any supplied answers.

• Keywords (perhaps the asker of the question can provide proposed keywords to make it easier for potential answerers to find it)

• Section information (in which sections this pair belongs) Perhaps the asker of the question can provide initial proposed sections to make it easier for potential answerers to find it, and as a way to initially assign which manager manages this questions.

• Order information (how questions are ordered relative to each other in a section). Perhaps this information is instead part of a section. The section manager maintains this information.

• Difficulty level. The manager assigns an official difficulty level, though possibly a voting system can be devised.

• Review rating (such as helped, 'didn't help,' flat out wrong, zen revelation!). This could be determined by voting. Possibly review ratings are associated with reviewers, so that I can go look for all answers that Joe Hacker thinks are Zen revelation.

More assorted metadata

• Format. The format of the text, such as structured-text, html-quote and plain.

• Email address. Contributor's e-mail address

• Contributor. Contributor's name

Sections

The FAQ can be partitioned into sections in many ways by the end user who is viewing the FAQ. The sections are on metadata associated with the question/answer pairs. For purposes of consistent management the FAQ is divided in a number of management sections, which may be equal to the default view on the FAQ.

Each management section has one or more maintainers/editors that can write official answers. Each question has a maximum of one official answer, and any number of comments. Anyone can contribute to the FAQ by writing comments -- the maintainer can take text from the comments to provide the official answer. Anyone can also contribute to the FAQ by entering new questions. The maintainers can rewrite the question texts, and remove redundant ones. The managers can also edit the meta data.

The ordering problem

• Ordering the question/answer pairs in different views can get complicated. We could devise a meta data structure to indicate the order for each section, where necessary. Some pairs can remain unordered, but some make more sense if they appear in order. Order could also be produced by difficulty rating.

• In the case of XML entry, the order of the FAQ entries in the default sections could 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 could make the XML input too complicated.

More snippets

• One entry can have more than one question

XML proposal

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 could be replaced by simple comment tags that are interpreted according to context. The usual way to enter a comment or an answer is through the web interface anyway, so contributors will not have to deal with all this XML verbosity.

Provision for linking to other entries

In addition to having a Cut, Past, Copy and otherwise general move capabilites to also have a Link capability, which creates a linked_to and linked_by reference set (I know, circular, gotta break it somehow) allowing you to move things around however you want, but still reference them from other places.

Versions

FAQ versions would be simply stored in different Folders and the current one will be indicated by a boolean property current (ZTables make this even easier). Versions would also be exported and backed up as XML documents.

Are versions useful in a collaborative FAQ?

Different layout options for the FAQ

• A simple plain one

• a full version that includes comments contributor info etc

• a tree version similar to Amos

ZTables

Z Tables has way to work with hierarchies. You can add hierarchy objects to the FAQ that add pseudo-structures to the the tabular structure.

For instance, say you have Topic and Subtopic as columns. You create a Hierarchy in the CoolFAQ object called Topics, telling it the first level in the hierarchy comes from values in the Topic column and the second from the Subtopic column. This automatically makes the following URLs work:

/CoolFAQ/Topics/

/CoolFAQ/Topics/manage

/CoolFAQ/Topics/Topic1/

/CoolFAQ/Topics/Topic1/manage

The Topics column appears to be a Folder in the CoolFAQ. You can dive into it and see a folderish management screen, allowing you to add documents to format it and images etc. You then see the Subtopics as subfolders. You can dive into them and add documents that format the nodes differently.

Filtering options/views

By difficulty level:

• Beginner

• General

• Advanced

By review rating:

• Not helpful

• Helpful

• Zen revelation

By topic, such as DTML, ZServer.

Or any other property, such as edited last week (as opposed to contributed), or all entries contributed by My Cat, even.

Sometimes combined views are also useful (all entries in the DTML section which were new since last week).

Other issues

Create automatic hyperlinks for URLs so that you can click on them in a browser instead of cutting and pasting.