[ZDP] Re: Resent: FAQ Tool Working Group

[Martijn Faassen]

Pavlos Christoforou wrote:
> 
> On Tue, 9 Mar 1999, Martijn Faassen wrote:
> 
> > Some things that would be nice:
> >
> > * Easy uploading of Structured Text formatted questions and answers.
> 
> I believe that a more 'structured' approach is better otherwise we will
> all need to agree on a common structured-text format. For instance
> looking at the structure of your submitted FAQ I could not easily see a
> way to add section information or meta-data like author, submitted time
> etc. Of course some can be created automatically upon submission but the
> functionality should be there.

Agreed that we need structured. I agree meta data is good and XML looks
like the best solution for this.

> > * Lots of different output formats; Structured Text and HTML perhaps
> > initially, later on Docbook SGML or possibly a FAQ SGML format about
> > there was some discussion, as well. The SGML can then be translated into
> > lots of stuff. Easy downloads of all these outputs.
> 
> I have changed the Zope FAQ site to support Stuctured-text and XML.

Great, thanks!

> > * Multiple sections
> >
> > * Ability to move question/answer pairs from one section to another.
> > Also possibly the ability to hyperlink (does a question involving how to
> > call External Methods from DTML belong in the DTML section or the
> > External Methods section? Both, it would seem, so put it in one section
> > and hyperlink from the other).
> 
> Right now is very easy to move entries around as each question resides in
> a folder which is contained in a corresponding section folder. It is a
> matter of cutting and pasting.

This sounds good. Would it be possible to expose this copy & paste
interface to a non Zope user, though? That is, to allow the FAQ
maintainer/editor to move things around without having to know Zope?
This isn't a big deal for the Zope FAQ, naturally, but it'd be useful if
this FAQ system is used in other settings.
 
> > * A comment system; people can add comments to existing FAQs. The editor
> > can then later choose to include some of these comments into the FAQ
> > text itself.
> 
> You can submit an answer to an already existing question. Both will be
> shown. Is this enough?

I'd be nice to allow people to attach corrections or comments to
existing answers, too, though. Also if a question is unanswered it'd be
nice if various people could attach different answers, to be folded into
one by the editor later. Comments would be very useful for instance in
case of simple typo fixes. Comments also should have a timestamp, so
that the editor can look at all recent comments.

> > * A 'contributor's section in which random individuals can upload new
> > questions, and questions with answers. The editor can then later move
> > these to appropriate sections and edit them for inclusion in the list.
> > Alternatively each section has a contributor's department.
> 
> Oh now I see. Well I quess I can arrange it so that any new submissions go
> in a different folder

The basic idea here is to have an 'official FAQ', and a 'FAQ in
development'. The Official FAQ is anything the editor touched and
fiated, the FAQ in development contains the Official FAQ, but has
attached extra questions (may be unanswered), question/answer
submissions from people off the net, comments to existing answers by
people off the net, etc.

Ordinarily, a person looking at the FAQ wouldn't want to see all
comments, but there should be an option to show these things; sometimes
comments from someone else can be useful, i.e. "this doesn't work for me
on NT, but I tried X and Y and now it works..".

> > * Versioning system. At the very least timestamp each question and
> > answer with the last edit date; possibly store older versions of
> > question/answer pairs. Ability for users to see all FAQs that were
> > recently updated, or that are new (in a particular section?).
> 
> Hmm I need some help on this. Right now questions are timestamped.

Timestamping is a great start. I'm not sure if versioning is actually
essential; perhaps enough is to back up the XML regularly so that it is
easy to go back to a previous version (of the FAQ or an individual
question/answer) if something goes catastrophically wrong.
 
> I have made all the suggested changes and you can view the results at:
> http://www.gaaros.com:9673/FAQ

Great! I'll take a look.
 
> Thanks for all the helpful suggestions

Thanks for your helpful programming. :)

Regards,

Martijn