[ZDP] Documentation...PTK, not XML is the answer...

Tom Deprez tom.deprez@uz.kuleuven.ac.be
Wed, 18 Aug 1999 10:52:24 +0200

I think this discussion becomes very clear if you have a look at :


just click on a category (preferable delphi :-))) ) and look how the
'front' page is made up.

Regards, Tom.

>Jim Salmons wrote:
>>         The original ZDP efforts to address the 'CoolFAQ tool' suffered
this same
>> bias. It was all about the presentation layer, like XML held the answer
to a
>> usable FAQ! In a model-view-controller sense, it was all about the view
>> layer.
>I didn't XML was about presentation at all; we used it more as a way to
>talk about the structure of a FAQ, and in that sense it's part of the
>model, not of the view. But it's true that the model should contain much
>more than just a document structure, and we've left too much of that
>>         But a FAQ is a BUSINESS PROCESS with a WORK PRODUCT which is a
>> The document-tail should NOT wag the PROCESS dog.
>You're right -- so please do continue steering us in what you consider
>to be the right directions. This is a serious invitation.
>>         If you do a FAQ tool, model and code what this is about. You
have a bunch
>> of roles: QuestionIdentifier, QuestionAsker, SubjectMatterExpert,
>> TechReviewer, EditorialReviewer, FAQLibrarian, FAQUser, etc.
>That all have different ways to view and modify one or more objects that
>represent the FAQ, right? Or is there no such FAQ document object at all
>anymore, somehow? (if this is the case I need further enlightenment). 
>>         The FAQProcess object (almost certainly there is more than one
>> object, but let's stick with the big picture here...) knows how to create
>> the relevant role objects, populate the roles with appropriate
>> inter-connected Activity objects (Activities being compositions of Task
>> objects), etc. etc.
>So a Person has a Role object. The role determines what a person can do
>with the FAQ.
>A role consists of a number of Activity objects..Here I'm unclear, is
>this something like, 'remove FAQ entries', 'Filter FAQ entries for
>editor Martijn'? And Task objects being
>smaller decompositions of this? 
>>         It is the job of a smart desktop framework to generate
role-specific views
>> onto this executing model. Almost all of the old CoolFAQ design document
>> lived in this presentation space of the FAQUser role and had nothing to do
>> with the REAL PROBLEM which is the BUSINESS PROCESS of creating and
>> maintaining a FAQ. It's a people problem, NOT a document design problem.
>> no fat, smart domain object design will produce a satisfactory result.
>Okay, I'm aware that it's a people problem. People need to be able to
>collaborate on a FAQ. This means for the user of the FAQ that he should
>be able to find the right FAQs (by using different views and filters on
>FAQCategories), and ask a new question (be a FAQAsker). A user is also
>turned into a FAQ answerer if he decides to answer a question (or
>perhaps that's only a FAQCommenter role). A FAQ editor looks at these
>FAQComments (or FAQPreliminaryAnswers) and edits them into a
>FAQMoreAuthorativeAnswer. :) A FAQLibrarian assigns FAQCategories to FAQ
>entries; a FAQAsker can also assign a set of FAQPreliminaryCategories to
>a FAQEntry. A FAQEditor (or possibly FAQLibrarian, or both) also needs
>to be able to remove redundant or unclear entries from the FAQ, possibly
>merging them with other FAQ entries.
>>         Tall order, you say. Yes, if you have to write these frameworks
>> scratch. I know, I have lead R&D efforts in the development of
>> Smalltalk-based role-based executable business models. But like anything,
>> designing and building a good framework is worth every effort in reuse and
>> extension.
>>         Now, back to the point. XML is important to us... for data
structuring and
>> presentation concerns. But it is the PORTAL TOOLKIT which holds the key to
>> our community's effort to produce, maintain and distribute documentation.
>>         It won't be there out of the gate. It is a diamond in the rough.
But it is
>> the RIGHT STUFF. The challenge will be to see if we can focus and harness
>> our collective volunteer efforts to take proper advantage of what DC has
>> wrought.
>>         ZOPE2/PTK rocks, what are we gonna roll with it?
>I agree that Zope2 + the portal toolkit are the keys to getting the
>community to fill in a FAQ -- a nice FAQ document structure is helpful
>but will do nothing if the community is not somehow able to use it
>Perhaps this discussion can give rise to a second design document, which
>describes the various roles and activities, and how we think about
>integrating these with the Portal Toolkit. For instance, any Zope Portal
>user can create a FAQ Entry in his homedirectory, which then can be
>published in the Zope FAQ. A difficulty arises if that FAQ Entry is
>deleted by the user; this shouldn't be allowed to happen -- and I don't
>know how the ZPT currently deals with this kind of thing. Similarly, how
>would the ZPT allow an editor to change a FAQ Entry created by another
>user? Questions abound. :)
>Thank you for your comments, Jim.
>ZDP maillist  -  ZDP@zope.org