CoolFAQ design document
Design by the ZDP group
Document by Rik Hoekstra
With some heavy editing by Martijn Faassen
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.
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.
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.
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:
More assorted metadata
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
The ordering problem
A complete FAQ entry might look like this:
<faq title='Zope FAQ'> <info> <version>0.2</version> <maintainer>Martijn Faassen</maintainer> <email>firstname.lastname@example.org</email> <date>11/3/99</date> </info> <section title='DTML'> <info> <maintainer>Martijn Pieters</maintainer> <email>email@example.com</email> <date>11/3/99</date> </info> <entry> <question contributor='Jim' firstname.lastname@example.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>
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.
FAQ versions would be simply stored in different Folders and the
current one will be indicated by a boolean property
Are versions useful in a collaborative FAQ?
Different layout options for the FAQ
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:
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.
By difficulty level:
By review rating:
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).
Create automatic hyperlinks for URLs so that you can click on them in a browser instead of cutting and pasting.
Printable Page Feedback