[ZDP] ZDP todo

[Rik Hoekstra]

As I announced last week I agreed to prepare a todo document for the ZDP.
Looting and raping the messages in the list archive I came up with the
following
document. Actually it is more of a (rather tentative) summary of a
discussion with
many ideas and many loose ends. A few decisions still have to be taken about
the way the CoolFAQ will be implemented.
Hopefully it is a useful starting point, however, though perhaps I missed a
few points. Your comments please.

Rik Hoekstra

=========================
ZDP TODO list


------1999-04-27--------
CoolFAQ


I - Design

- 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)

- 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.

- The order of sections and entries is important as the relative sequencing
is derived from the order they appear in the xml doc.

(a)Hierarchical structure is nice because it maps directly onto Zope's
object system. Thus you can use Zope's through the web gui to modify, cut
and paste your entries etc. 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 maintainers.

(b)The xml part is a useful feature that will allow the exporting
and importing of xml formatted FAQ's and at a later stage allow convertion
into other formats.


Proposed solution:

xml faq doc is composed of entries alone, and subelements of the
entries indicate the section, subsection etc that the entry belongs to.

Proposed solutions:

* 1 XML "document" per FAQ item, it should be "standalone"
* Sections are built dynamically by traversing lower tree
  structure looking for matching documents.

OR provide multiple questions and answers.

* relating one or more answers to a given question and visa-versa
* providing contributor sections for each question, answer and comment.

[This solution is completed with a proposed review procedure
Here's how it works... someone creates a new Question in some area of
FAQ, it has the following characteristics:

	* Question itself (hoozah! Imagine!)
	* Topical keywords
	* Difficulty level
	* Author information

Then, it is "answered":

	* Answer itself
	* Additional keywords
	* Difficulty level
	* Author information
	* Review rating (0-10 based on 'helped,' 'didn't help,' 'flat
	  out wrong'.

So each Question is printed,followed by it's "answers" (yes there might
be multiple approaches, etc), and then people can "review" these answers
providing some value in how substantive and useful they were for that
particular person.]



- Use XML in order to provide a relatively clear and easy
method to structure the FAQ entries. Eventually
(hopefully) the FAQ will migrate to the DocBook format.

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

- FAQ will be divided into sections containing 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)

- XML FAQ entries should not be complicated.


- 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.

- One entry can have more than one question

- 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.

- 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.


II - versions
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.

Unsolved question: are versions useful in a collaborative FAQ?


III- Different viewing options for the FAQ.
  - A simple plain one,
  - a full version that includes comments
    contributor info etc
  - a tree version similar to Amos


Proposals:

(1) Get the most basic FAQs higher up in the section, and more specific ones
lower in the
section.

or

Avoid including information about the order of the entries or sections
in the xml document. Order of entries is *normally* not an issue, but there
are times, obviously, when it's critical to the intelligibility of the
document.

REMARK: This may be solved by proposal 2, as it provides 'pseudo structures'

(2) Is each Q&A going to be stored in an entry in the Z-Table and
representation of
the "natural" outline structure that most FAQs would want:

Topic 1
    Q1.1
    Q1.2
    Subtopic a
         Q1.2.1
    Subtopic b
 Topic 2
    Q2.1
    Q2.2

Z Tables has a nice solution to the above called a Hierarchy.  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.

IV- Filtering options/views
By "difficulty" level:

	* Beginner
	* General
	* Advanced
	* Zen Revelation

by topic (DTML, ZServer)

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

and combined,


V Other issues

- 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.

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

- Some kind of What's New page that will show you the most recently
modified entries.  This way you can easily read only modified items.