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

[Martijn Faassen]

Jim Salmons wrote:

[snip] 
>         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
implicit.

>         But a FAQ is a BUSINESS PROCESS with a WORK PRODUCT which is a document.
> 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 mega-process
> 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. And
> 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 from
> 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
effectively.

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.

Regards,

Martijn