[ZDP] résumé

Tom Deprez Tom Deprez" <tom.deprez@village.uunet.be
Thu, 26 Aug 1999 22:43:16 +0200


Hi all,

I hope you don't mind that I write this report in plain text. I haven't yet
found the time to immerse myself into XML.
Following is a sort of résumé of what can be found at the XML doc
'Requirements for ZDP'.
I don't know if I did this correctly. I just did it the way I thought it
should be: I combined them and tried to create a global picture of it. I
hope you like it! Happy reading.

This text is offcourse open for debate, which would be easier to handle if
some of the tasks defined later one were already created. What is always the
case in real life :-)).

ZDP will stand for (it's intention) :

How-To's
Tutorials
FAQ
Reference Manual
ZBook

ZDP will have two entries :

1. Non approved ZDP Docs = ZDP work floor (Work Area)
2. Approved Docs = ZDP oasis (Approved Area)

So ZDP contains in fact 2 sites. But not 2 different objects. The sites are
dynamically created through filtering on some objects properties. (see
later)

How-To's, Tutorials, FAQ, parts of Reference Manual start in the ZDP Work
Area until they are approved (see later)
ZBook can not be categorised under approved / non approved docs, because
chapers will most likely always change.(? open for discussion)




RULES!

The implementation should be flexible enough so that it easy to extend it
later on.
All ZDP categories should be implemented in the same style so that the view
is the same for the whole ZDP site
People working on ZDP are devided into roles and to this roles some specific
tasks/priveliges are attached. Roles/tasks will be likely the same for all
ZDP categories.
It should be very easy to link/reuse parts of ZDP with all ZDP categories
ZDP style/rules should be so easy (mostly automatic) as if they are
non-existing so that every visiter can contribute to ZDP.





LIFE CYCLE OF ZDP DOCS

Because all ZDP categories have the same outcome, i.e. they present some
information to the reader, they basically all will follow the same life
cycle, except the duration of start to finish and the way they follow will
be different. The cycle is as follows:

1. Information is presented (birth - start of a thread), I call it here
'DRAFT DOC'
2. Comments can be added (growing)
3. The information can/will be altered to commit to the comments
4. The comments which are taken into account are removed or hidden (?) so
that they will not clutter the thread too much (or make visible turn away
because they have to read too much non relevant information)
5. The information is almost perfect. I call it here 'FINISHED DOC'
6. The 'Approval' is asked
7. The 'FINISHED DOC' is checked and 'APPROVED'
8. Comments are still possible but are most likely not frequent

This life cycle also allows us to determine some roles and their tasks :

Visitors/Contributors :
  every visitor must be able to contribute so these should be the same!
  a Visitor is able (but NOT needed) to register him/herself (-> benefit,
that some customisations can be done, according to his/her previous visits)

Editors/Authors/Maintainers:
  they who maintain/enhance/update the DRAFT to FINISHED DOC
Approver:
  Give approval for transfering the doc to the APPROVED Area.

As I said, the proces for all ZDP-categories is almost the same, only the
duration/start (=interaction) is different :

Small interaction /  small editing : How-to's, Tutorials,  Reference Manual

   The information should almost be perfect and most comments are just fixes
of bugs,...
   In fact, the DRAFT will never appear on the site, the author who wrote
the doc should normally bring a FINISHED (tested) DOC. But I still want to
call this a DRAFT!
   Update is preferable done by the author

Medium interaction / medium-heavy editing : ZBook:

  The information presented is a view of the writer to the subject. Visitors
can write a comment (= their view).
  In fact the information will never be perfect! :-)
  Also here, update preferable done by the author himself

Heavy interaction / heavy editing : FAQ:

  The information is non-existing! A question is asked and the answer
(=information) will be formed during the comments-thread.
  Most likely the question is asked by a 'Visitor' and the answer is also
given by a 'Visitor'.
  Maintainers of the FAQ categorie, should form the answer during the
thread...
  Which means a heavy use of the comments-thread and a lot of maintanence,
follow-up!

We see some special things here:
   Visitors can sometimes become Editors. This when they contribute a DRAFT
   It should be possible to let this transformation (for this specific DOC)
be done automatically!
   Normally an Editor should also not be an Approver for the same DOC!






THE STRUCTURE OF THE DATA

Base class:

Date/Time - Date and time when comment is given
Content - Text of comment
pre_Content - The modified comment before published (when editing it)
Name/E-mail - Name/Email of person giving comment

----------

Doc class (inherit base class) :

id - An ID as an unique identifier.

ZDP Categorie - To which category this doc belongs (see above for ZDP
categories)

categories - The category (or list). (entered by an Editor,
enhanced/corrected by the Approver)

Platform - Doc is for specific platform (or compatible List) (entered by an
Editor, enhanced/corrected by the Approver)

Server- Doc is for specific server (or compatible List) (entered by an
Editor, enhanced/corrected by the Approver)

products - The product used (or list of used products). (entered by an
Editor, enhanced/corrected by the Approver)

Author - Alias/name of author

Content - The DRAFT or later on the FINISHED DOC (= link to a base object)

Comments- The links to the comments on this DOC (comments are base objects!)

Links - Links to other objects! (like how-to's, examples,... which are
already in the approved area!)

NeedApproval - The doc is ready to be approved  (entered by an Editor)
   A time check needs to be incorporated here! i.e. when an editor forgets
to set this boolean to true, so that we don't get orphans!

Approved_Date/Time - the date/time this DOC is approved (entered by an
Approver)

IsApproved - The DOC is approved (entered by an Approver)

isLocked - To keep it simple, whenever the Editor or any other user works on
a question, it will be locked so noone can edit it. Yes, we could develop a
merge process, but I think that would be far too complex for version 1.0.

--------

How-to class (inherit DOC class)

--------

ZBook class (inherit DOC class)

--------

FAQ class (inherit DOC class)

question - Link to a base class containing the question

answer = content of inherited DOC class.

isPublished - If an entire new question was sent to the queue, the question
should not be published. This field may be removed in other data struture
suggestions. (? needed this one?)

---------

Tutorial class (inherit DOC class)

source_code - link to downloadable code
script - link to script which guides user through tutorial (implementing on
a later stage)

--------

Reference Manual (inherit DOC class)

??
??



HOW ZDP WILL WORK?

Entering of ZDP

A visitor/editor is able to set to customisations (only if she/he is
registered (free offcourse)! or by cookies) like eg. filtering: give me all
approved or non approved or all docs;  show/ don't show me the comments of
an approved doc; give me only the docs concerning these products,
categories; thus the visitor/editor wants to be alerted when a comment is
added....) (*a)

Display of the ZDP categories (see above)
A link will bring the visitor to his/her choosen categorie.
According to his customisation (approved/non-approved, category, products)
the docs will be shown (The way on how this shown to the visitor  depends
heavely on the CHOOSEN category!) (*b)
A link brings the visitor to the page of his/her choice:

The THREAD is displayed. A question or draft is displayed on top of the
page. In the FAQ section, followed by the DRAFT Answer. Then followed by
comments (in approved section, only when visitor has checked this option in
his customisation form). The comments are ordered from youngest (top) to
oldest (bottem) added. (*c)

The visitor is allowed to add a comment (preferable in plain text), (but
html, structured text is allowed -> can be incorporated in a later stage!)
(*d)




TASKS WHICH NEED TO BE DONE

[1] A 'ZDP StyleBook' needs to be created (including ways to easy display
code - Python code??).

[2] The first possible Categories (not same as ZDP Categories!) / Products
(all available now?) / Platforms/ Servers need to be determined

[3] The classes need to be created and the base framework of the different
ZDP categories.

[4] The properties for registered visitores need to be determined and a form
+ class needs to be created (*a)
eg. filter on approved/non-approved; filter on products/categories; show
comments on approved docs y/n; notify on email; server; platform
(ps. non-approved docs need to show their comment ALWAYS! otherwise
redundant information, ...)

[5] Per categorie a presentation layout has to be created (*b)
eg. FAQ, How-To's, Tutorials:
       A tree displaying the different categories (take custimisation into
account!): expand/collapse the docs
     Reference Manual
       A tree displaying the different tags, expand/collapse the properties,
etc.
     ZBook
        A tree displaying the different chapters

[5] The presentation of the THREADs need to be created (*c)

[5] The allowance to add comments to the THREAD need to be created (*d)

[6] A search engine (OR, AND, ...) needs to be created to allow several
searches (searches need to be determined too! eg.
product/categorie/author...)

[As soon as possible] The license needs to be determined (Open Content, Open
Publication License)




ZDP CATEGORIE DEPENDEND TASKS

Reference Manual

There should be categories (e.g. DMTL tag). Each category will have its own
form for the user to fill out. For example it is very important that the
"DTML tag" has a section for attributes, which may not be important for
other categories. On the other hand the "DTML tag" should have an example
associated with it, which is most likely applicable for all of the
categories.

Each entry in the same category should have a similar look. Common elements
such as attributes should be seperate and only be referenced in an entry
(e.g. the tag). For example, the expr attribute may apply for several tags;
it would be insufficient to explain the attribute every time you create a
tag which contains the attribute.

One of the problems I usually face is that a Reference has many styles and
is hard to read. I think we should definetely have a core set of editors
that will proof-read the content for a common tome of the text. (BTW, I face
this problem every day at work.)

How-To's

See list for needed how-to's on requirement list (can be used as test after
ZDP Frame is finished!)

Tutorials

Will make extensive use of a 'Source-interpreter' (See 'StyleBook')
On a later stage a script will be programmed (which people were working on a
teaching project???) which makes it possible to guide people trough the
tutorial

ZBook

Initial chapters need to be determined
Editors/maintainers/approvers need to be searched. (After ZDP Frame is
finished)

FAQ

Approvers need to be searched (After creation of ZDP Frame)





Pffff, that's it.... I did my best.... hope you agree! Hope I didn't forgot
something.... If I did, just yell!

Can somebody swiftly make the ZDP frame? So that we can discuss this DRAFT
through a THREAD? :-)

Stephan, can you put this on your site?

Tom.